Advanced search¶

The Advanced search panel¶

This section will outline how to use AtoM’s advanced search interface. The advanced search interface is used to find descriptions in AtoM that contain text matching a search query. The advanced search panel is available on all archival description search and browse pages, at the top of the results - click on the panel header to expand or collapse it:

Users can also go directly to the search page with the advanced search panel expanded by using the “Advanced search” hyperlink available in the drop-down menu that appears when a user places the cursor in the search box located in the AtoM header bar.

In the advanced search panel, a user can select “and, or, not” operators to build powerful Boolean search queries, limit search terms to specific archival description fields, and/or apply a number of different filters to limit or narrow the results returned along specific criteria, all via a friendly user interface.

To search for archival descriptions using the advanced search panel:

1. Place your cursor in the search box located in the AtoM header bar. A drop-down menu will appear below the search box - to access the advanced search interface, click on the “Advanced search” link in the drop-down menu.

   

   Alternatively, you can use the Browse menu to navigate to Browse > Archival descriptions, and then click on the Advanced search panel to expand it.

2. AtoM will redirect you to the advanced search screen:

3. To begin searching, enter a search term into the first search field at the top of the Advanced search panel, under the heading, “Find results with”:

4. Use the drop-down menu to limit your search query to a specific field in the archival description templates. The default setting is to search any field. Options include:
   • Title
   • Archival history
   • Scope and content
   • Extent and medium
   • Subject access points
   • Name access points
   • Place access points
   • Genre access points
   • Identifier
   • Reference code

5. Use the “Add new criteria” button to build multi-part queries with Boolean search operators via the user interface - by using these operators, you can narrow your search, combine terms, or exclude terms. AtoM will add a new set of fields below, into which you can enter your terms - repeat steps 3-5 as necessary. You can use the X to the right of the fields to remove a row of fields from your Boolean query if needed.

• Use AND to combine search terms to narrow your search: e.g. search vancouver AND “city hall” to return only descriptions that contain both search terms
• Use OR to to combine search terms to broaden your search: e.g. search vancouver OR “city hall” to return descriptions that contain either search term
• Use AND NOT to exclude terms: e.g. search vancouver AND NOT “city hall” to return descriptions that include vancouver but do not contain the phrase “city hall”

6. The filters available under the “Limit results to:” section of the Advanced search panel will allow you to limit the results to a specific repository or archival unit.

   
   • Repository: Limit the search to the holdings of a specific archival institution. The drop-down menu will be populated by all of the archival institution records in AtoM. Select the repository or archival institution you wish from the drop-down; when you submit your query, results returned will only include those associated with the selected repository.
   • Top-level description: This is an auto-complete field that will populate with all of the top-level descriptions held in AtoM (generally, fonds and collections, but if a series or another level is set as the top level of a descriptive hierarchy, it will be available in the list). Begin typing the title of a top-level description, and the auto-complete will populate the drop-down menu with matching selections. Click on one to select it - search results will be limited to archival descriptions found within the chosen top-level description’s descendants - i.e. children.

7. In the section below that, labelled “Filter results by:”, you can also add filters to your search to limit the results returned to specific parameters. The functions of each search filter are outlined below:

• Level of description: This filter will limit the returned search results to a specific level of description.
• Digital object available: Use this filter to determine if a the search results returned include digital objects (e.g. images, audio or video files, text documents, etc.), or by selecting “No”, include only results without digital objects.

• Copyright status: AtoM archival description templates include a the ability to add Rights statements, drawn from elements of the PREMIS (Preservation Medata: Impmlementation Strategies) metadata standard maintained by the U.S. Library of Congress. Through this module, a user can add a copyright status to an archival description (with values including Public Domain, Under copyright, or Unknown). This filter will limit search results to those descriptions where a PREMIS Rights copyright status has been added matching the selection in the filter’s drop-down menu. For more information, see: Rights.
• General material designation: This is a filter that is particular to a controlled field found within the RAD template for archival descriptions - it is a controlled vocabulary drawn directly from the Canadian Rules for Archival Description, and managed in one of AtoM’s taxnomies and used to define the type of material found within an archival unit. Select a GMD term from the drop-down menu to limit search results to descriptions that have been been marked with the matching GMD value.

8. Finally, the last section, labelled “Filter by date range:”, will allow you to search against the internal StartDate and EndDate values of of creation events associated with an archival description. For more information on using the date range search in AtoM, see below, Date range search filter.
9. If you wish to restart your search and quickly clear all filters and boolean fields, you can use the “Reset” button located at the bottom of the Advanced search panel. AtoM will reload the page, with all filters and parameters removed.
10. When you have entered all of your search parameters, click the “Search” button in the button block at the bottom of the Advanced search panel to view the results of your search query. AtoM will reload the page, with a count of results above the Advanced search panel, and the results listed below. Results will appear in order of relevance below the button block. If there are more than 10 results, a pager will be included at the bottom of the results page. Remember, you can click on the header of the Advanced search panel to collapse it out of view while you browse the results.

11. Click on the blue titles of the results stubs to navigate to that result’s specific page. Navigating back will bring you back to your original list of results; however, navigating to the “Advanced search” page from the search box will require you to restart your search from the beginning.
12. Your search can be modified at any time and the results refrehsed accordingly by simply changing the required search terms and fields, and clicking “Search” once again. You can also restart your search at any time; simply click the “Reset” button in the button block of the Advanced search panel.

Date range search filter¶

The date range search allows users to search for any records whose active dates (e.g. dates of creation, accumulation, etc.) either overlap, or fall exactly within, a selected range. AtoM expects ISO 8601 formatted date values for searching - i.e. YYYY-MM-DD. Note that the fields include calendar widgets, to provide users with a graphical interface for date selection if desired - alternatively, you can manually enter your range directly into the text field. Whenever only YYYY values are entered, AtoM will automatically add -01-01 to values in the Start date field, and -12-31 to values in the End date field.

Important

When searching for a date range, AtoM searches against the values in internal, ISO-8601 startDate and endDate fields - those hidden from users, and formatted as YYYY-MM-DD, YYYY-MM, or YYYY. This is not to be confused with the Display date field, which is shown to public users, and allows you to use typographical marks to express approximation or uncertainty:

This means, if you have NOT included internal start and end date values, then your description(s) will not be returned when performing a date range search!

There are 2 ways of searching dates, represented by the radio button options in the Date range search interface - “Overlapping” (which is the default), and “Exact.”

The Overlapping option is a broadly inclusive search: any records whose dates overlap the user input range will be returned. For example, a search for a range from 1950-1970 would return descriptions with the following dates:

• 1945 - 1990
• 1945 - 1950
• 1970 - 1990
• 1955 - 1965
• 1955 - (no end date)
• (no start date) - 1980

The Exact option means that records must fall exactly within the specified parameters to be returned as a result. A search for 1950-1970 using the “Exact” option would not return any of the results listed above - but its results returned might include values such as:

• 1950 - 1955
• 1952 - 1969
• 1950 - 1970
• 1964 - 1969
• 1968 - 1970

To better clarify these options, some example diagrams have been included below to indicate the difference, illustrating how each option behaves for closed ranges (both start and end date included), and open ranges (where either a start or end date is included, and the second date is left blank). In the following images, results in green will be returned by the search query; results in red will be excluded from the results:

Closed range example¶

Overlapping:

Exact:

As you can see, the “Overlapping” option is very inclusive, while the “Exact” option is much more strict in terms of the results returned.

Open end date example¶

You can also input only a start date, or an end date, into the date range search if desired. If a user gives just a start date, it is interpreted to mean ‘filter to records that were active after this date’ - in other words, ‘end date of record > user supplied start date.’

Overlapping:

When the “Overlapping” option is used, records which start before the specified start date will be included if their date range extends into the specified parameter.

Exact:

When the “Exact” option is used, records starting before the specified start date range are excluded.

Open start date example¶

If the user gives just an end date, it means ‘filter to records that were active before this date’ - in other words, ‘start date of record < user supplied end date.’

Overlapping

When the “Overlapping” option is used for search with a specified end date but no start date, records whose ranges extend beyond the specified range may be included, if their start dates extend into the specified range.

Exact

When the “Exact” option is used, any record whose end date falls outside of the specified parameter will be excluded.

Using the date range search filter¶

When you place the cursor in the start date or end date fields of the date range search, a calendar drop-down menu will appear. This “datepicker” offers a graphical user interface for selecting the date, if desired.

Click on a day in the calendar to select that as your start or end date. You can also navigate through the months using the black forward and back buttons.

The month and year can also be adjusted via the two drop-down menus:

Alternatively, you can also ignore the calendar widget, and simply enter a date directly into the text field. AtoM expects the dates to be formatted as YYYY or YYYY-MM-DD. If you enter only the year, then AtoM will add -01-01 to start dates and -12-31 to end dates when the search query is submitted - for example, if you search for 1950 - 1970, AtoM will submit the query as 1950-01-01 (January 01, 1950) to 1970-12-31 (December 31, 1970). You can also specify an open range, by entering just a start date or just an end date.

Note

If you enter the dates in the wrong format, such as YYYY-MM, your search will return no results! In this case, AtoM will provide a warning above the date range fields:

Once you have entered your desired date range, use the radio button options to the right of the input fields to specify how the date range should be performed. “Exact” means that the start and end dates of descriptions returned must fall entirely within the date range entered, while “Overlapping” is much more inclusive, and any description whose start or end dates touch or overlap the target date range will be returned. See above for an illustration of the differences between Overlapping and Exact when returning results for:

• Closed range (start and end date)
• Open range (no end date)
• Open range (no start date)

If you click the (?) Help icon, a tooltip will appear below the fields with a brief explanation of the difference between “Overlapping” and “Exact.”

When you have entered all desired parameters, use the “Search” button to submit your query. Remember, you can also use other Advanced search filters or facets to further refine your search!

Back to top

Advanced search using the AtoM Search box¶

AtoM implements Elasticsearch, a distributed search server based on Apache Lucene, which acts as the application’s search and analytic engine. Elasticsearch is not integrated directly into AtoM code as a library, but as a service deployed in the same network which AtoM interacts with through a REST ful API.

This provides a number of options for advanced searching from within the search box. What follows is a list of the most commonly used tools available in the AtoM search box.

Boolean operators¶

In AtoM, Boolean search operators are supported in the search box and in the Adanced search menu. Boolean searching is a particular application of what is known as Boolean logic, a subset of algebra used for creating true/false statements. Since computers operate in binary (using ones and zeroes), computer logic can often be expressed in boolen terms (true/false). Boolean expressions use a number of operators, the most common of which are AND, OR, and NOT - using Boolean operators in terms of search queries (i.e. Boolean search) allows a user to limit, widen, or otherwise define a search in granular terms - for example, searching “fonds OR collection” would widen a search to include results that have either term in their title.

Using the Boolean operators available in AtoM allows users to build complex queries from anywhere in AtoM using the general search box located in the AtoM header bar, without having to navigate to the Advanced search interface.

Tip

By default in AtoM, the Boolean search settings of AtoM are set to use OR as the default operator when multiple search terms are entered. This means that by default, a search for chocolate cake will return results that include “chocolate” OR “cake”.

Using Boolean operators in the AtoM search box:

• Use AND to combine search terms to narrow your search: e.g. search vancouver AND “city hall” to return only descriptions that contain both search terms
• Use OR to to combine search terms to broaden your search: e.g. search vancouver OR “city hall” to return descriptions that contain either search term
• Use AND NOT to exclude terms: e.g. search vancouver AND NOT “city hall” to return descriptions that include vancouver but do not contain the phrase “city hall”

Important

Boolean operators can be combined, but there is a default precedence built into how Elasticsearch handles them - NOT takes precedence over AND, which takes precedence over OR. If you wish to combine Boolean operators, you may want to use parentheses ( ) to group clauses. See the table below for more details on grouping, and other operators available.

Other Boolean operators available in AtoM:

Symbol	Use
"	Term enclosed in quotes must appear exactly as provided. Example: “towel” will find towel, but not towels.
+	Term after “+” must be in the result. Example: +tea cricket requires that results that must contain the term tea in them, and may have the term cricket.
-	Term after “-” must not be in the result. Example: -tea cricket requires that results that must not contain the term tea in them, and may have the term cricket.
?	Single character wildcard. Example: p?per will find paper and piper, but not pepper.
*	Multiple character wildcard. Example: galax* will find galaxy and galaxies, but not galactic.
~	Fuzzy search. Will return results with words similar to the term. Example: fjord~ will find fjord, fjords, ford, form, fonds, etc.
&&	Boolean operator. Can be used in place of AND. Will cause an error if combined with spelled-out operators. Example: Arthur && Ford AND Zaphod will fail; Arthur && Ford && Zaphod will succeed.
!	Boolean operator. Can be used in place of NOT. Will cause an error if combined with spelled-out operators.
^	Boost relevance. Multiplies the relevance of the preceding term by the number following the symbol, affecting the sorting of the search results. Example: paranoid android^5 gives results containing the term “android” 5x the relevance as results containing only the word “paranoid”, and will sort them closer to the start of the search results.
\	Escapes the immediately following character, so that it is treated as text, rather than as a special character. For example, to search for “(1+1):2”, use the following: \(1\+1\)\:2
()	Used to group search clauses. This can be useful if you want to control the precedence of boolean operators for a query, e.g. (coffee NOT tea) OR cream will return different results than coffee NOT (tea OR cream). Without grouping, by default in Elasticsearch, NOT takes precedence over AND, which takes precedence over OR.
[]	Closed interval range search. Example: [“Frogstar” TO “Magrathea”] will return results in the alphabetic range between “Frogstar” and “Magrathea”, including”Frogstar” and “Magrathea”.
{}	Open interval range search. Example: {“Frogstar” TO “Magrathea”} will return all results in the alphabetic range between “Frogstar” and “Magrathea”, excluding”Frogstar” and “Magrathea”.

For further examples of the use of these Boolean operators, users can consult the Zend Lucene search documentation as Elasticsearch is built on the same Apache Lucene base as the Zend framework. Developers interested in fine-tuning these settings, or technical users interested in how Elasticsearch operates may wish to consult the query string query Elasticsearch reference documentation for more information on Elasticsearch’s default behaviors, and possible configurations.

Export advanced search results in CSV format¶

Any authenticated (i.e. logged in) user can generate a CSV export of advanced search results. The CSV export, after it is generated, is made available for download from the jobs page.

When downloaded, the file will be compressed in a ZIP archive - there are many free utilities (likely there is one already included on your computer) that will allow you to “unzip” a ZIP file.

For more information, see the CSV export documentation:

• Export search and browse results in CSV format.

Back to top