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
Merged
Merged
Changes from all commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
95af3ad
docs(advanced search): update naming to advanced search
b516f46
docs(advanced search): update naming to advanced search
a103925
docs(advanced search): explain comparison operators
2af9fc0
docs(advanced search): explain is like / regex
2778e26
Merge branch 'main' into wip/dsp-1651-search-docs
tobiasschweizer 0e3ca22
docs(advanced search): explain is like / regex
d80ab9a
docs(advanced search): explain mactches
a5b3b94
docs(advanced search): explain matches for linking props
fd0ef9c
docs(advanced search): explain matches
d4bb3ad
Update advanced-search-user-docs.md
gautschr 8d3c3f2
docs(advanced search): fix typos
43d25bc
docs(advanced search): fix typos
0dcd07e
Merge branch 'main' into wip/dsp-1651-search-docs
File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
File renamed without changes
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 (SPARQL) 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 or both are optional, either a resource class has to be selected or at least one property has to be specified, | ||
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. | ||
- `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 to or greater than search value, overlap of date periods or date period begins after search value. | ||
- `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 to or less than search value, overlap of date periods or date period ends before search value. | ||
- `exists`: value for the given property exists. | ||
- `is like`: search value is contained in a text using the SPARQL [REGEX](https://www.w3.org/TR/sparql11-query/#func-regex) function (supports regular expressions). | ||
- `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 via the support of regular expressions | ||
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) | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
# Advanced search (Component) | ||
|
||
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 used individually 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. | ||
|
||
## 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 advanced search form. | ||
gravsearch | string | Send the gravsearch query back. | ||
|
||
## Examples | ||
|
||
Advanced search panel | ||
|
||
```html | ||
<!-- param route is where the router-outlet is defined for search results --> | ||
|
||
<dsp-advanced-search [route]="'/search'"></dsp-advanced-search> | ||
|
||
<router-outlet></router-outlet> | ||
``` | ||
|
||
![Advanced search panel with a search example](../../assets/images/advanced-search.png) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.
"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 comment
The 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 comment
The 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 comment
The 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 comment
The reason will be displayed to describe this comment to others. Learn more.
https://docs-api.dasch.swiss/03-apis/api-v2/query-language/#date-comparisons
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.
However, I am not sure how many technical details a user of the GUI should know