.. include:: /includes.rst.txt .. comments - headings # with overline, for parts * with overline, for chapters = for sections - for subsections ^ for subsubsections " for paragraphs * for H5 + for H6 .. 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 Ontolgoy 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, unless changed by your EDG Administrator. .. figure:: _images/edg_search_panel_new.png :alt: TopBraid EDG Search Panel :align: center :class: edg-figure-l **TopBraid EDG Search Panel** 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. The table in the Search panel shows only assets of the selected type including any of its sub types. Selecting Search Results Columns ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ability to add/remove **Columns** is managed by clicking the **+** button, which is always visible on the right hand side of the table header. 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_panel_columns.png :alt: TopBraid EDG Search Results Panel Column Selection :align: center :class: edg-figure-l **TopBraid EDG Search Results Panel Column Selection** 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_search_panel_selected_columns.png :alt: TopBraid EDG Database Column Search Panel :align: center :class: edg-figure-l **TopBraid EDG Database Column Search Panel** 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_search_panel_numbered.png :alt: TopBraid EDG Numbered Concept Search Panel :align: center :class: edg-figure-m **TopBraid EDG Numbered Concept Search Panel** 1. **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** 2. **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** 3. **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** 4. **Settings** menu for Search Panel. Lets you personalize the behavior of this panel. * **Hide Quick Asset Type Selector** – will hide the type selector drop-down list but leave the type selector button 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** .. index:: pair: Searching; Searching for Assets Searching for Assets -------------------- You can search among the assets of selected type by using: * **Free text** search of all textual propertye values - The entered text is matched against any property with a textual value; e.g., label, description, note. The text string can be a partial match. For example, searching for “rock” will be interpreted as *rock* and return results for “rocket”. Multiple word free text searches will be joined with a logical AND: * ``A B`` implies A AND B * ``“A B”`` matches the full term (in exactly that order) * ``A OR B`` is an explicit logical OR; any number of OR terms is supported, such as ``A OR B OR C OR D`` .. figure:: _images/edg_search_panel_input_group.png :alt: TopBraid EDG Searching for Assets using Free Text :align: center :class: edg-figure-m **TopBraid EDG Searching for Assets using Free Text** * **Filter** specific property values - The filter icon will open a dialog containing the current active filters or a listing of available properties from which one or more can be selected for filtering. This dialog works like the **Columns** drop down, including the ability to select properties of related assets. For each property selected in the **Filter** dialog, select the *match type* and enter or select its search criteria. The match type determines how EDG will use the search criteria. Different properties can use different match types. The search criteria specified for the selected properties are combined together to produce an overall search result. The search criteria will not be applied until clicking 'Ok'; while clicking off the dialog will cancel the changes. .. figure:: _images/edg_search_panel_filter_dialog.png :alt: TopBraid EDG Searching for Assets Filter Dialog :align: center :class: edg-figure-m **TopBraid EDG Searching for Assets Filter Dialog** .. Unless an explicit line break is desired, leave the cell contents in the list-table on a single line and use word-wrap to view and edit the contents. .. list-table:: :header-rows: 1 :widths: 33 67 * - **Match Type** - **How a search value matches instance property-values** * - contains - This is the default match type for text properties. The entered text matches any resource where the specified property's value contains the search string (case-insensitive). Example: For a city-name property, the search string “lis” would match instances having city-name values such as “Lisbon”, “Lisboa”, and “Minneapolis”. * - equals - This is the default match type for relationship properties. For attributes, the entered text matches any resource where the specified property's value exactly matches the search string (case-sensitive). For relationships, the entry field becomes an auto-complete field for selecting a related asset and will present a list of auto-complete options that match the entered text, a list of the names (labels) of any resources that begin with the entered text. * - starts with - The entered text matches any resource where the specified property's value starts with the search string (case-insensitive). * - regex (regular expression) - For text properties, the entered text is used as a regular expression to match property values (case-insensitive). Example: For a city-name property, the search string “^lis” matches city-name values that begin with “lis”, e.g., “Lisbon” and “Lisboa” but not “Minneapolis”. Conversely, “lis$” matches only at the name’s end. For relationships, the regular expression is matched with the labels of the related resources. * - any value - This match type has no corresponding search criteria. It simply searches for *any* occurrence of the selected property. Example: This match type can be used to determine how extensively a property is used. * - min/max number of values - This match type finds resources that have a number of values for the selected property between the specified minimum and maximum values (inclusive). Example: If most resources in a Data Assets collection have labels in three languages, entering a label search with a min/max values range of 0 to 2 would return those instances with fewer than three labels. * - no value - Like *any value*, above, this match type has no corresponding search criteria. It searches for items with *no* occurrence of the selected property. Example: This match type can be used to clean up a Data Assets Collection and check for any remaining values. * - boolean - This is the default match type for Boolean properties. The selected value (*true* or *false*) matches any resource with a matching property value. * - nested form - This is available only for relationship properties. Adds an embedded search form for properties whose type is another class * - min/max (inclusive) - This is the default match type for numeric properties. This matches resources where the specified property's value is within the specified range, inclusive. * - min/max (exclusive) - This matches resources where the specified property's value is within the specified range, exclusive. * **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 affects only 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_panel_annotated.png :alt: TopBraid EDG Labelled Image for Search :align: center :class: edg-figure-m **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.txt .. include:: ./lucene_integration_and_query_language.rst.txt