.. include:: /includes.rst.txt .. comments - headings # with overline, for parts * with overline, for chapters = for sections - for subsections ^ for subsubsections " for paragraphs .. index:: Searching in EDG .. _searching_target: Searching in EDG ================ Searching in EDG is supported at across collections as well as within collections and their included collections. **Search the EDG** is the feature that supports EDG-wide search. The **Search Panel** that is available when viewing or editing a specific collection supports search within that collection and its included collections. The main header bar in EDG provides a search feature that has access to both Search the EDG, Quick Lookup, and Find Code for Reference Data. .. figure:: _images/search.jpg :alt: Search header :align: center :class: edg-figure-l By default, when collections are enabled for Search the EDG, this is the default result. If no collections are enabled for Search the EDG then Quick Lookup is the default. See below for details on each option. The images below show different results due to the fact that Search the EDG only has one enabled collection applicable for the result, where the quick lookup searches across all collections. .. index:: pair: Searching; Quick Lookup Quick Lookup ------------- Quick Lookup lets you find assets (resources) across all asset collections in EDG by entering their name. This is an auto-complete look up field. As you type, any resource whose label is prefixed by the search text will appear in a popup list. Label and Preferred label with a language tag in the current browser’s language or with no language tag will be matched against the entered string. Selecting a listed resource will navigate you to that resource in a new tab. .. figure:: _images/quick_lookup.jpg :alt: Quick Lookup :align: center :class: edg-figure-l .. index:: pair: Searching; Search the EDG Search the EDG -------------- **Search the EDG** searches across all EDG resources that EDG administrator and/or manager of a specific collection elected to include in the index. This decision can be made upon creation of a collection and can also be made later on the Manage tab of the collection or through Governance Model. An entire subject area or business area can be included in Search the EDG by checking the box as shown below. To see which collections are enabled for Search the EDG, navigate directly to the search results page (URL/search) and see the asset collection facets. Selecting a search result from the header bar will open that result in the editor page in a new tab. If you would like to view more results or navigate to the Search the EDG page for further details or to use faceted search, click "Continue in Search the EDG". Submitting a search from the home page opens a page with the search results summary. Your search key words will be matched against text in any of the properties of the collections that are managed by Search the EDG. .. note:: You may have fields that contain text tagged with different languages, note that search will be performed across all values, irrespective of the language. .. figure:: _images/search_edg_header.jpg :alt: Search EDG header :align: center :class: edg-figure-l In the search results page, you can: * refine or completely change the search terms and re-execute the search, * filter results via facets, * click on any of the result results to see more information about it, * make comments about any of the found resources and see comments made by other users, * endorse any of the found resources and see endorsements made my others, * access interactive visual views and diagrams for a found resource – what is available depends on a type of the item, * access results and facets via API’s (see below), * search using Lucene query expression. .. figure:: _images/edg-results.jpg :alt: TopBraid Search the EDG Page :align: center :class: edg-figure-l **TopBraid Search the EDG Page** All properties of the collection will be indexed for search as well as applicable facets. The results of search are sorted by score, then alphabetically. The facet results list shows the top 10 facets for the results. The score is calculated based on the number of matches to the term within the document. Lucene also offers query boosting per field (be sure to check use advanced syntax). For example searching: :: *id^3 -will find anything that ends in "id" and assign it a weight of 3, boosting those results .. index:: pair: Searching; Lucene Query Language Customizing Search Results """""""""""""""""""""""""" Search Results can be customized through DASH Property Roles (https://datashapes.org/propertyroles.html) which allows each datatype that is indexed to utilize different properties in the result summary. Observe the search results below, their respective home graphs have been configured with different property roles for the same type (Database Column). Database Columns from the Human Resources Data collection will include information from the 'column of' property. Database Columns from the Product Sales Data collection will include information from the 'physical datatype' property. .. figure:: _images/edg_search_the_edg_property_role.png :alt: TopBraid Search the EDG with defined Property Roles :align: center :class: edg-figure-l **TopBraid Search the EDG Page** Example Dash Property Role ************************** Assigning a Dash Property Role can be done through the Ontology Editor. The below image of the form panel shows the Property Shape ``edg:DataElement-physicalDatatype`` being assigned a **Key info** Property Role. .. figure:: _images/edg_search_property_shape.png :alt: Property Shape being assigned a DASH Property Role :align: center :class: edg-figure-l **TopBraid EDG Form Panel** Using Lucene Query Language """"""""""""""""""""""""""" In addition to simply using search keywords, users can combine them with Lucene operators to form richer search queries. By default wildcard search has been implemented before and after the search term. For example, searching for the string "customer" without quotes actually searches for \*customer\*. Check the box for Use Advanced Syntax for Lucene query expressions: **Example Lucene Operators** * **Wildcards (* ?):** “?” performs a single character wildcard search and “*” performs a multiple character wildcard search. For example, ``te?t`` matches “test”, “text”, etc and ``Ken*`` matches all values that start with “Ken”. *product* -will find anything with the word “product” in it. name -will find anything that ends in “name” * **Fuzzy (~):** Matches similar spellings of the word. For example ``john~``, will match “john” and “jean”. The similarity threshold is set to 0.5 by default. You can adjust it using any number between 0 and 1. For example, john~0.8. * **Prohibit (-term or NOT term):** excludes matches that contain the term after the “-” or “NOT” symbols. For example, ``Ken* -Kentucky`` matches all values that start with “Ken” but excludes anything that matches ‘Kentucky’. * **Modifiers (AND OR):** using the AND operator will match items that contain both terms while the ``OR`` operator matches an item that contains either of the terms. * **Range queries:** using TO operator will match items with the range of values. For example, “Finland TO Germany” in curly brackets. If you want to limit this to a particular field (for example) only a label, use :{}. For example, skos_prefLabel:{Finland TO Germany}. .. index:: pair: Searching; Search Panel .. _search_panel: Search Panel ------------ The Search panel lists assets of the selected type in a sortable table. From here, users can further filter displayed assets, export information, save searches and perform other operations. .. note:: This panel is not available for ontologies, please see ontology specific documentation in :ref:`working_with_ontologies_target`. By default, this panel will display up to 1,000 result rows by default, unless changed by your EDG Administrator. .. figure:: _images/edg_search_panel.jpeg :alt: TopBraid EDG Search Panel Page :align: center :class: edg-figure-l **TopBraid EDG Search Panel Page** Selecting Asset Type in the Search Panel """""""""""""""""""""""""""""""""""""""" The Type Selector shown at the top of the Search panel lets you to select the type of assets to show in the table. You can select an asset type either from the **Type** drop-down list (it supports autocomplete so to select you can start typing the name of an asset type you are interested in) or you could click on the button next to the drop-down list to open a browsable hierarchical navigator listing available asset types. Table in the Search panel shows only assets of the selected type including any of its sub types. Selecting Search Results Columns """""""""""""""""""""""""""""""" The **Columns** icon to the right of the **Filter** icon lets you add columns to the search results table. Properties available for selection depend on the type of the asset. For example, Database Column is selected as the asset type in the image below. You will be able to select any properties defined for the Database Column asset type. .. figure:: _images/edg_search_results_column_selection.png :alt: TopBraid EDG Search Results Column Selection Page :align: center :class: edg-figure-l **TopBraid EDG Search Results Column Selection Page** You can scroll through the list of properties available for selection or quickly find a property by typing in the **Search** field at the top of the dropdown. Clicking on a property will select it as column. Currently selected columns will be shown at the top of the drop down list. To remove a selected column, click on the “x” icon next to it. For properties that are relationships, you will see “>” to the right of the property name – as shown in the screenshot above. If you click on it, EDG will present a list of properties for the related asset. This way, you can add as columns not only properties of assets you are looking at, but also properties of related resources – these are called nested columns. The screenshot below shows a results table that we will get after selecting as columns 1) “record count” property that belongs to related assets – namely, Database Tables that assets of the selected type, Database Columns, are associated with via “column of” property – this is an example of a nested column and 2) “physical datatype” property that belongs directly to the Database Columns. .. figure:: _images/edg_database_column_search.png :alt: TopBraid EDG Database Column Search Page :align: center :class: edg-figure-l **TopBraid EDG Database Column Search Page** If a column is a nested column, the header row will display the connecting relationship name in the square brackets. Cell values for such columns will display the related assets before displaying the value of the selected property. You can select more than one level of nesting. Actions in the Search Panel *************************** The Search panel has **New** button. Clicking on it, will let you create a new asset of the currently selected type. The Search panel also offers several other actions that can be performed on the search query or on the search results. These actions and the corresponding menus and buttons are shown in the next screenshot and explained in the text below it. .. figure:: _images/edg_numbered_concept_search.jpeg :alt: TopBraid EDG Numbered Concept Search Page :align: center :class: edg-figure-l **TopBraid EDG Numbered Concept Search Page** 1. **Save Search** button. Will bring up the dialog to save searches. Saved searches are public and can be seen and used by any other users of this collection. To run or delete previously saved searches use the **Search Library** panel. .. figure:: _images/edg_save_query.jpeg :alt: TopBraid EDG Save Query :align: center :class: edg-figure-m **TopBraid EDG Save Query** 2. **Settings** menu for Search Panel. Lets you personalize the behavior of this panel. * **Hide Quick Asset Type Selector** – will hide the type selector menu but leave the type selector menu in place. * **Disable auto-searching** – this will change the behavior of the free text search box. You will need to hit enter when ready to submit instead of the results auto populating as you type. * **Add a column for each filter** – checking this box will add a column to the results table each time you add a property as a filter for the search. * **Return local results only** – this will filter out included collections. .. figure:: _images/edg_search_panel_settings.jpeg :alt: TopBraid EDG Settings for Search Panel :align: center :class: edg-figure-m **TopBraid EDG Settings for Search Panel** 3. **Export**. Provides access to the various export options for search results. The entire search results are exported unless you check certain results rows, then export will be limited to those rows. .. figure:: _images/edg_search_export.jpeg :alt: TopBraid EDG Search Results Export Options :align: center :class: edg-figure-m **TopBraid EDG Search Results Export Options** 4. **More**. Provides access to several actions that can be performed on selected results. Check the row boxes for the items you want to perform these actions on. * **Delete** * **Add to Asset List** – which is another panel in the editor used for bulk functions or bookmarks * **Add to Basket** – which is the basket for all of EDG located in the main header bar * **Edit assets** – will launch a :ref:`batch_edit` wizard tool * **Show on Map Results Panel** – this option will be available only if :ref:`map_explorer_panel` is enabled. Clicking on it will display selected items on the map – provided that they have geo coordinates. .. figure:: _images/edg_search_result_actions.jpeg :alt: TopBraid EDG Search Result Actions :align: center :class: edg-figure-m **TopBraid EDG Search Result Actions** .. index:: pair: Searching; Searching for Assets Searching for Assets -------------------- You can search among the assets of selected type by using: * **Free text** (any property). This matches your string against any property with textual values e.g., label, description, note, etc. This query is wildcard. For example, searching for “rock” will be interpreted as *rock* and return results for “rocket”. Multiple word free text searches will be AND not OR. * A B means an implicit AND * “A B” matches the full term (in exactly that order) * A OR B means an ‘or’ – infinite chains are supported such as A OR B OR C OR D .. figure:: _images/edg_search_free_text.jpeg :alt: TopBraid EDG Searching for Assets using Free Text :align: center :class: edg-figure-m **TopBraid EDG Searching for Assets using Free Text** * **Filter** on specific property values. The filter icon will open a drop down listing available properties and letting you select one or more. This works similar to **Columns** drop down, including ability to select properties of related assets. For each property selected using **Filters** drop down, you will be able to enter a search criteria and specify the type of match. Type of match determines how EDG will use the value you enter in that field to search for matching data. Different properties can use different match types. Search criteria specified for each property are combined together to produce an overall search result. .. figure:: _images/edg_search_filter.jpeg :alt: TopBraid EDG Searching for Assets using Filter :align: center :class: edg-figure-m **TopBraid EDG Searching for Assets using Filter** .. list-table:: :header-rows: 1 * - **Type of Match** - **How a search value matches instance property-values** * - contains - DEFAULT for text properties: Finds resources that contain the entered search string (case-insensitive) in the property value. Example: Search text “lis” on a city-name property would match instances having city-name values such as “Lisbon”, “Lisboa”, and “Minneapolis”. * - equals - DEFAULT for relationships: For attributes, this will match the entered string exactly to the property value (case-sensitive). For relationships, this becomes an auto-complete field for selecting a related asset. As you start typing a value in a relationship field, you will get a list of autocomplete options that match the text you’ve typed so far—a list of the names (labels) of any resources that begin with the typed letters. * - regular expression - For text properties, searches text using a regular expression that matches a property-value (case-insensitive). Example: Search text “^lis” as a regular expression matches city-name values that begin with “lis”, e.g., “Lisbon” and “Lisboa” but not “Minneapolis”. Conversely, “lis$” would match only at the name’s end. For relationships, does similar matching, but on the labels of related resources. * - any value - At least one value exists for the selected property (count >= 1). Example: See how extensively a property is used. * - min/max number of values - Finds resources whose number of values for selected property fall in the range specified by the one or two numbers you enter. Example: If most resources in a Data Assets Collection have labels in three languages, entering a label search with values-range 0 to 2 would return those instances with fewer. Leaving min range empty and just using 2 in the max field will return the same results. * - no value - No values exist for the search property (count = 0). Example: Use to clean up a Data Assets Collection and check for remaining work. * - boolean - DEFAULT for Boolean properties: Search values restricted to true/false instead of free-text * - nested form - Available only for relationships: Adds an embedded search form for properties whose type is another class * - min/max (inclusive) - DEFAULT for numeric properties: Finds resources that are within the range of entered search criteria, inclusively. * - min/max (exclusive) - Finds resources that are within the range of entered search criteria, exclusively. * **Refine** field is displayed at the top of each column under the column name. Entering a value in this field refines the results displayed in the table. The **Refine** is similar to **Filter** except that it only affects the *visibility* of assets that are already in the results table, without affecting which assets are loaded into results table, i.e., the underlying search scope is unchanged and refine only narrows data already in the table. .. figure:: _images/edg_search_refine.jpeg :alt: TopBraid EDG Searching for Assets using Refine :align: center :class: edg-figure-m **TopBraid EDG Searching for Assets using Refine** If you have incomplete search results, over 1000 if you have the default settings, you can still search the entire collection as well as export all the search results: .. figure:: _images/edg_search_labelled.png :alt: TopBraid EDG Labelled Image for Search :align: center :class: edg-figure-l **TopBraid EDG Labelled Image for Search** .. index:: pair: Searching; Search Library Panel .. _search_library_panel: Search Library Panel """""""""""""""""""" This panel will show the list of searches saved using the Search panel. What it shows is determined by the asset collection you are currently in. You will be able to select and execute a search. You will also be able to delete saved searches. The settings menu lets you configure how much information about a search should be displayed. .. figure:: _images/edg_search_library_panel.jpeg :alt: TopBraid EDG Search Library Panel :align: center :class: edg-figure-l **TopBraid EDG Search Library Panel** .. seealso:: For expert users familiar with RDF, EDG supports the `SPARQL Query Language`_ for search, see :ref:`sparql_target`. .. seealso:: For software developers and others familiar with GraphQL, EDG supports the `GraphQL`_ for search, see :ref:`graphql_target`. .. include:: ./search_results_via_api.rst .. include:: ./lucene_integration_and_query_language.rst