New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs(advanced search): update naming to advanced search (DSP-1651) #295
Changes from 10 commits
95af3ad
b516f46
a103925
2af9fc0
2778e26
0e3ca22
d80ab9a
a5b3b94
fd0ef9c
d4bb3ad
8d3c3f2
43d25bc
0dcd07e
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,65 @@ | ||
# Advanced Search Component | ||
|
||
## Introduction | ||
|
||
The `AdvancedSearchComponent` allows for the creation of complex queries using a graphical widget. | ||
The widget's contents are then turned into a string representing a Gravsearch (SPAQRL) query to be sent to DSP-API. | ||
|
||
A query consists of the following elements: | ||
- ontology (data model) selection | ||
- selection of a resource class belonging to the selected ontology (optional) | ||
- specification of properties, comparison operators, and values (optional). | ||
|
||
Although selection of a resource or a property ore both are optional, either a resource class has to be selected or at least one property has to be specified, | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ore -> or (unless we're mining now 😜) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. fixed in 8d3c3f2 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. typo: ore > or There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. already caught be @mdelez :-) |
||
otherwise the query is not considered valid and cannot be submitted. | ||
|
||
## Comparison Operators | ||
|
||
Depending on the value type of the chosen property, | ||
one or more of the following comparison operators can be selected: | ||
|
||
- `is equal to`: value equality: same number, exact same string, overlap of date periods, same target resource. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "matching date periods" is probably more clear here (same for the instances below), unless you truly do mean an overlap There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The thing is that each date is represented as a period in DSP-API. All kinds of overlap count as a match, e.g., a search for a date with day precision will match a value with year precision. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. That's fair. It's fine the way it is then :) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I understand why you asked though. Maybe it could be covered in more detail in the DSP-API docs and could be linked to from here? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. However, I am not sure how many technical details a user of the GUI should know |
||
- `is not equal to`: value inequality: not same number, not exact same string, no overlap of date periods, not same target resource. | ||
- `is greater than`: value comparison: number is greater than search value, date period begins after search value. | ||
- `is greater than or equal to` value equality / value comparison: number is equal or greater than search value, overlap of date periods or date period begins after search value. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. equal to There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. fixed in 8d3c3f2 |
||
- `is less than`: value comparison: number is less than search value, date period ends before search value. | ||
- `is less than or equal to`: value equality / value comparison: number is equal or less than search value, overlap of date periods or date period ends before search value. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. equal to There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. fixed in 8d3c3f2 |
||
- `exists`: a value for the given property exists. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. sometimes you start with a "A" value, sometimes not > make it consistent There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. fixed in 8d3c3f2 |
||
- `is like`: search value is contained in a text using the SPARQL [REGEX](https://www.w3.org/TR/sparql11-query/#func-regex) function (support of regular expressions). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. support of -> supports There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. fixed in 8d3c3f2 |
||
- `matches`: | ||
- text property: search value matches the text ([Lucene Query Parser Syntax](https://docs-api.dasch.swiss/08-lucene/lucene-query-parser-syntax/)). | ||
- linking property: matches the specified linked resource. | ||
|
||
## Search Examples | ||
|
||
### Regular Expressions (is like) | ||
|
||
The `is like` operator lets the user search for texts that are *like* the search value, supporting regular expressions. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. the search value, supporting regular expressions. -> the search value via the support of regular expressions. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. fixed in 8d3c3f2 |
||
In this example, all books are found whose title contains "Narrenschiff" followed by a space and some other characters like "(lat.)" or "(dt.)". | ||
|
||
For general information about regular expressions see this [interactive tutorial](https://regexone.com). | ||
|
||
![Advanced search panel with a search example](../../assets/images/advanced-search-regex.png) | ||
|
||
### Lucene Parser Syntax (matches) | ||
|
||
Used with a text property, the `matches` operator lets the user search for texts that *match* the search value, | ||
supporting [Lucene Query Parser Syntax](https://docs-api.dasch.swiss/08-lucene/lucene-query-parser-syntax/). | ||
In this example, all persons are found whose names contain "Ja" and "ob" with a character in between (represented by the wildcard "?"). | ||
This search finds "Jacob" as well as "Jakob". | ||
|
||
**Note the difference between regular expressions and Lucene parser syntax!** | ||
|
||
![Advanced search panel with a search example](../../assets/images/advanced-search-match.png) | ||
|
||
### Specifying a Linked Resource (matches) | ||
|
||
Used with a linking property, the `matches` operator lets the user search for a linked resource that matches the specified properties. | ||
In this example, the user writes a query looking for all letters that have an author that: | ||
1. was born after January 1st 1650 | ||
2. whose family name is "Bernoulli" | ||
|
||
This is different from the "is equal to" operator that lets the user specify a certain person (selected from a list). | ||
|
||
![Advanced search panel with a search example](../../assets/images/advanced-search-linked-resource.png) | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,25 +1,25 @@ | ||
# Extended search (Component) | ||
# Advanced search (Component) | ||
|
||
The extended search allows you to filter by project, by source type (resource class), or by the metadata (properties) of source types. Each filter can be standalone or combined. The metadata field can be precisely filtered with criteria such as "contains", "like", "equals to", "exists" or in case of a date value with "before" or "after". In addition, for a metadata field that is connected to another source type, it's possible to filter by this second source type. If you are looking for the source type "Photograph" with the metadata field "Photographer", which is connected to source type "Person", you can search for photograph(s) taken by person(s) who is born before February 1970. The result of this request will be an intersection of the two source types. | ||
The advanced search allows you to filter by project, by source type (resource class), or by the metadata (properties) of source types. Each filter can be standalone or combined. The metadata field can be precisely filtered with criteria such as "contains", "like", "equals to", "exists" or in case of a date value with "before" or "after". In addition, for a metadata field that is connected to another source type, it's possible to filter by this second source type. If you are looking for the source type "Photograph" with the metadata field "Photographer", which is connected to source type "Person", you can search for photograph(s) taken by person(s) who is born before February 1970. The result of this request will be an intersection of the two source types. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Each filter can be standalone or combined. -> Each filter can be used individually or combined. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. fixed in 8d3c3f2 |
||
|
||
## Parameters | ||
|
||
Name | Type | Description | ||
--- | --- | --- | ||
--- | --- | --- | ||
route | string | Route to navigate after search. This route path should contain a component for search results. | ||
toggleExtendedSearchForm | boolean | Trigger toggle for extended search form. | ||
toggleExtendedSearchForm | boolean | Trigger toggle for advanced search form. | ||
gravsearch | string | Send the gravsearch query back. | ||
|
||
## Examples | ||
|
||
Extended search panel | ||
Advanced search panel | ||
|
||
```html | ||
<!-- param route is where the router-outlet is defined for search results --> | ||
```html | ||
<!-- param route is where the router-outlet is defined for search results --> | ||
|
||
<dsp-extended-search [route]="'/search'"></dsp-search> | ||
<dsp-advanced-search [route]="'/search'"></dsp-advanced-search> | ||
|
||
<router-outlet></router-outlet> | ||
``` | ||
<router-outlet></router-outlet> | ||
``` | ||
|
||
![Advanced search panel with a search example](../../assets/images/extended-search.png) | ||
![Advanced search panel with a search example](../../assets/images/advanced-search.png) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,6 @@ | ||
# DSP-UI SEARCH module | ||
|
||
DspSearchModule allows to make simple searches or extended searches in DSP-API. In extended search, resource class and its properties related to one specific ontology are selected to create your query. It is also possible to write Gravsearch queries to target specific data with the expert search form. | ||
DspSearchModule allows to make simple searches or advanced searches in DSP-API. In advanced search, resource class and its properties related to one specific ontology are selected to create your query. It is also possible to write Gravsearch queries to target specific data with the expert search form. | ||
|
||
## Prerequisites | ||
|
||
|
@@ -14,7 +14,7 @@ DspSearchModule is part of @dasch-swiss/dsp-ui, follow [the installation guide]( | |
|
||
## Components | ||
|
||
This module contains various components to search. The main component is the dsp-search-panel, which contains the dsp-fulltext-search, dsp-extended-search and dsp-expert-search. All of them can be used standalone or in combination in dsp-search-panel. | ||
This module contains various components to search. The main component is the dsp-search-panel, which contains the dsp-fulltext-search, dsp-advanced-search and dsp-expert-search. All of them can be used standalone or in combination in dsp-search-panel. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. standalone -> individually (standalone is correct and understandable, I would just personally use individually) |
||
|
||
### [Search panel](/developers/dsp-ui/documentation/search/search-panel) | ||
|
||
|
@@ -23,7 +23,7 @@ Fully customizable panel. You can set the following parameters in dsp-search-pan | |
- route: string; url-route for search results | ||
- filterbyproject: string; project iri to limit search results by project | ||
- projectfilter: boolean; selection of all projects to filter by | ||
- advanced: boolean; additional menu with advanced / extended search | ||
- advanced: boolean; additional menu with advanced search | ||
- expert: boolean; additional menu with expert search / gravsearch "editor" | ||
|
||
If everything is set to false or undefined the search-panel is a simple full-text search. [Read more](modules/search/search-panel) | ||
|
@@ -51,7 +51,7 @@ We suggest to define a route for the search-results in the app.routing | |
] | ||
``` | ||
|
||
### [Extended / advanced search](/developers/dsp-ui/documentation/search/extended-search) | ||
### [Advanced search](/developers/dsp-ui/documentation/search/advanced-search) | ||
|
||
Generic search filter tool to limit search results to ontology and resource class and / or properties. | ||
|
||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -18,7 +18,7 @@ nav: | |
- Introduction Search: how-to-use/search/index.md | ||
- Search-panel: how-to-use/search/search-panel.md | ||
- Fulltext search: how-to-use/search/fulltext-search.md | ||
- Extended search: how-to-use/search/extended-search.md | ||
- advanced search: how-to-use/search/advanced-search.md | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. to be picky: Advanced There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. fixed in 8d3c3f2 |
||
- Expert search: how-to-use/search/expert-search.md | ||
- Action module: | ||
- Introduction Action: how-to-use/action/index.md | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
typo: SPARQL
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
fixed in 8d3c3f2