From 5145bc93003906b0d20977e3022c01eb02cbaf1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarik=20G=C3=BCrsoy?= Date: Mon, 10 Jun 2024 14:03:36 +0200 Subject: [PATCH] Add documentation for the search syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pushed-by: Tarik Gürsoy Co-authored-by: Tarik Gürsoy --- docs/de/user/search/index.md | 76 +++++++++++++++++++++++ docs/en/user/search/index.md | 69 ++++++++++++++++++++ gradle/changelog/added_documentation.yaml | 2 + 3 files changed, 147 insertions(+) create mode 100644 docs/de/user/search/index.md create mode 100644 docs/en/user/search/index.md create mode 100644 gradle/changelog/added_documentation.yaml diff --git a/docs/de/user/search/index.md b/docs/de/user/search/index.md new file mode 100644 index 0000000000..cf19eea7c6 --- /dev/null +++ b/docs/de/user/search/index.md @@ -0,0 +1,76 @@ +--- + +title: Suchsyntax + +partiallyActive: true + +--- + +Der Suchbereich enthält alle notwendigen Informationen, um die Suchoption des SCM-Managers zu nutzen (ausgenommen die Plugin-Funktionalität). + +### Arten von Suchanfragen + +Es gibt zwei Arten von Suchen. Die erste Art ist die einfache Suche. Eine einfache Suche besteht nur aus Suchbegriffen und beinhaltet keine der unten gelisteten Operatoren (z.B. 'AND'). +Jeder Suchbegriff einer einfachen Suche wird implizit am Ende mit dem \*-Operator erweitert. Dadurch findet man mit dem Suchbegriff 'Repo' auch den Begriff 'Repository'. +Die zweite Art von Suche ist die Expertensuche. Sobald eine Suchanfrage einen Operator beinhaltet, dann gilt diese Suchanfrage als Expertensuche. +Die Art von Suche ermöglicht es, komplexe Suchabfragen zu erstellen. Allerdings werden Suchbegriffe hier nicht implizit mit einem \*-Operator erweitert. Dementsprechend muss hier der \*-Operator bei Bedarf explizit gesetzt werden. + +### Modifikatoren + +Hinweis: Sie können keine Wildcards als erstes Zeichen einer Suche verwenden. + +Definition | Beispiel +---------|---------- +? - Wildcard für ein einzelnes Zeichen | "Ultimate?Repo" – findet z.B. `Ultimate-Repo`, `Ultimate Repo`, `Ultimate+Repo` +\* - Wildcard für mehrere Zeichen | "Ultimat*y" - findet z.B. `Ultimate Repository`, `Ultimate-Special-Repository`, `Ultimately` + +### Bereiche + +Bereichsabfragen ermöglichen den Abgleich von Dokumenten, deren Feldwerte zwischen der unteren und der oberen Grenze liegen, die in der Bereichsabfrage angegeben sind. Bereichsabfragen können die obere und untere Grenze einschließen oder ausschließen. Die Sortierung erfolgt lexikografisch. + +Bereiche sind nicht auf numerische Felder beschränkt. + +Definition | Beispiel +-----------|------------ +\[ … TO … ] - inklusiver Bereich | "creationDate:\[1609459200000 TO 1612137600000]" – findet z.B. Repositories, die zwischen dem 01.01.2021 und dem 01.02.2021 erstellt wurden +{… TO …} - exklusiver Bereich | "name:{Aida TO Carmen}" – f"name:{Aida TO Carmen}" – findet Namen zwischen Aida und Carmen, jedoch ohne die beiden Namen einzuschließen + +### Boosting + +Mit dem Boosting können Sie die Relevanz eines Dokuments steuern, indem Sie seinen Term verstärken. + +Definition | Beispiel +---------|---------- +term^number | "ultimate^2 repository" – erhöht die Relevanz von `ultimate` + +Standardmäßig ist der Boost-Faktor 1. Obwohl der Boost-Faktor positiv sein muss, kann er kleiner als 1 sein (z. B. 0,2) + +Standardmäßig werden Repository-Namen um 1,5 und Namespace-Namen um 1,25 geboostet. + +### Boolesche Operatoren + +Hinweis: Logische Operatoren müssen in Großbuchstaben eingegeben werden (z. B. „AND"). + +Operator | Definition | Beispiel +---------|-----------------------------------------------------------------------------------|--------- +AND | Beide Terme müssen enthalten sein | "Ultimate AND Repository" – findet z.B. `Ultimate Repository`, `Ultimate Special` `Repository` +OR | Mindestens einer der Terme muss enthalten sein | "Ultimate OR Repository" – findet z.B. `Ultimate` `Repository`, `Ultimate User`, `Special` `Repository` +NOT | Der folgende Term darf nicht enthalten sein, "!" kann alternativ verwendet werden | "Ultimate NOT Repository" – findet z.B. `Ultimate user`, schließt z.B. `Ultimate Repository` aus +\- | schließt den folgenden Term aus der Suche aus | "Ultimate Repository -Special" – findet z.B. `Ultimate Repository`, schließt z.B. `Ultimate Special Repository` aus +\+ | Der folgende Term muss enthalten sein | "Ultimate +Repository" – findet z.B. `mein Repository`, `Ultimate Repository` + +### Gruppierung + +Die Suche unterstützt die Verwendung von Klammern zur Gruppierung von Begriffen, um Teilabfragen zu bilden. Dies kann sehr nützlich sein, wenn Sie die boolesche Logik für eine Abfrage steuern möchten. + +Definition | Beispiel +-----------|----------- +() – Terme zwischen den Klammern werden gruppiert | "(Ultimate OR my) AND Repository" – findet z.B. `Ultimate Repository`, `my Repository`, schließt z.B. Super Repository aus. Entweder "Ultimate" oder "My" muss existieren, "Repository" muss immer existieren + +### Phrasen + +Eine Phrase ist eine Gruppe von Begriffen in einer bestimmten Reihenfolge. Wenn Sie nach bestimmten Phrasen suchen möchten, können Sie das " Zeichen verwenden. + +Definition | Beispiel +-----------|----------- +"" - Begriffe innerhalb der Anführungszeichen werden als Phrase gesucht | "Ultimate Repository" – findet `Ultimate Repository`, aber nicht `Repository Ultimate`, `Ultimate` oder `Repository` diff --git a/docs/en/user/search/index.md b/docs/en/user/search/index.md new file mode 100644 index 0000000000..74f052e27f --- /dev/null +++ b/docs/en/user/search/index.md @@ -0,0 +1,69 @@ +--- +title: Search Syntax +partiallyActive: true +--- +The search area includes all the necessary info to make use of the SCM-Managers search option (excluding the plugin functionality) + +### Types of queries +There are two types of queries. The first is the simple query. +A simple query only contains terms and does not contain any of the operators listed below (for example 'AND'). +Every term used in a simple query get implicitly extended with the \* operator at the end. This means that searching for 'Repo' will also match the term 'Repository'. +The second type of query is the expert query. Any query that contains at least one operator is considered as an expert query. This query type allows for complex searches. +But terms used in the expert query are not extended with the \* implicitly. A user has to add them explicitly to a term. + + +### Modifiers +Note: You can not use wildcards as the first character of a search + +Definition | Example +---------|---------- +? - single character Wildcard | "Ultimate?Repo" – finds e.g. `Ultimate-Repo`, `Ultimate Repo`, `Ultimate+Repo` +\* - multiple character Wildcard | "Ultimat*y" - finds e.g. `Ultimate Repository`, `Ultimate-Special-Repository`, `Ultimately` + + +### Ranges +Range Queries allow one to match documents whose field(s) values are between the lower and upper bound specified by the Range Query. Range Queries can be inclusive or exclusive of the upper and lower bounds. Sorting is done lexicographically. + +Ranges are not reserved to numerical fields. + +Definition | Example +---------|---------- +\[ … TO … ] - inclusive range | "creationDate:\[1609459200000 TO 1612137600000]" – finds e.G. repositories created between 2021-01-01 and 2021-02-01 +{… TO …} - exclusive range - multiple character Wildcard | "name:{Aida TO Carmen}" – finds e.G. repositories with names between Aida and Carmen, excluding these to values + + +### Boosting +Boosting allows you to control the relevance of a document by boosting its term. + +Definition | Example +---------|---------- +term^number | "ultimate^2 repository" – makes the term `ultimate` more relevant + +By default, the boost factor is 1. Although the boost factor must be positive, it can be less than 1 (e.g. 0.2) + +By default Repository names are boosted by 1.5, namespace by 1.25. + +### Boolean Operators +Note: Logical Operators must be entered in upper case (e.g. "AND"). + +Operator | Definition | Example +---------|------------|--------- +AND| Both terms must be included | "Ultimate AND Repository" – finds e.g. `Ultimate Repository`, `Ultimate Special Repository` +OR| At least one of the terms must be included | "Ultimate OR Repository" – finds e.g. `Ultimate Repository`, `Ultimate User`, `Special Repository` +NOT| Following term may not be included, "!" may be used alternatively | "Ultimate NOT Repository" – finds e.g. `Ultimate user`, excludes e.g. `Ultimate Repository` +\-| excludes following term from search | "Ultimate Repository -Special" – finds e.g. `Ultimate Repository`, excludes e.g. `Ultimate Special Repository` +\+| Following term must be included | "Ultimate +Repository" – finds e.g. `my Repository`, `Ultimate Repository` + +### Grouping +Search supports using parentheses to group clauses to form sub queries. This can be very useful if you want to control the boolean logic for a query. + +Definition | Example +-----------|----------- +() – terms inside parentheses are grouped together | "(Ultimate OR my) AND Repository" – finds e.g. `Ultimate Repository`, `my Repository`, excludes e.g. `Super Repository`. Either "Ultimate" or “My” must exist, “Repository” must always exist + +### Phrases +A phrase is a group of terms in a certain order. If you want to search for certain phrases then you can use the " operator. + +Definition | Example +-----------|----------- +"" - terms inside the quotes are searched for as a phrase | "Ultimate Repository" – finds `Ultimate Repository` but not `Repository Ultimate`, `Ultimate` or `Repository` diff --git a/gradle/changelog/added_documentation.yaml b/gradle/changelog/added_documentation.yaml new file mode 100644 index 0000000000..29bdc04ff1 --- /dev/null +++ b/gradle/changelog/added_documentation.yaml @@ -0,0 +1,2 @@ +- type: added + description: The documentation for the search syntax has been added to the official docs