Add descriptions for queries R-W (#2217)

* Add descriptions for queries R-W

* Apply suggestions from code review

Co-authored-by: István Zoltán Szabó <[email protected]>

---------

Co-authored-by: István Zoltán Szabó <[email protected]>

Author: abdonpijpelink

output/schema/schema.json

@@ -431,12 +431,35 @@ query-dsl-match-all-query,https://www.elastic.co/guide/en/elasticsearch/referenc
 query-dsl-match-bool-prefix-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-match-bool-prefix-query.html
 query-dsl-match-none-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-match-all-query.html#query-dsl-match-none-query
 query-dsl-match-query-phrase,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-match-query-phrase.html
-query-dsl-match-query-phrase-prefix,https://www.elastic.co/guide/en/elasticsearch/reference/query-dsl-mlt-query,{branch}/query-dsl-match-query-phrase-prefix.html
-https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-mlt-query.html
+query-dsl-match-query-phrase-prefix,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-match-query-phrase-prefix.html
+query-dsl-mlt-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-mlt-query.html
 query-dsl-multi-match-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-multi-match-query.html
 query-dsl-nested-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-nested-query.html
 query-dsl-parent-id-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-parent-id-query.html
 query-dsl-percolate-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-percolate-query.html
 query-dsl-pinned-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-pinned-query.html
 query-dsl-prefix-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-prefix-query.html
-query-dsl-query-string-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-query-string-query.html
+query-dsl-query-string-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-query-string-query.html
+query-dsl-range-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-range-query.html
+query-dsl-rank-feature-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-rank-feature-query.html
+query-dsl-regexp-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-regexp-query.html
+regexp-syntax,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/regexp-syntax.html
+query-dsl-script-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-script-query.html
+query-dsl-script-score-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-script-score-query.html
+query-dsl-shape-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-shape-query.html
+query-dsl-simple-query-string-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-simple-query-string-query.html
+query-dsl-span-containing-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-containing-query.html
+query-dsl-span-field-masking-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-field-masking-query.html
+query-dsl-span-first-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-first-query.html
+query-dsl-span-multi-term-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-multi-term-query.html
+query-dsl-span-near-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-near-query.html
+query-dsl-span-not-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-not-query.html
+query-dsl-span-or-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-or-query.html
+query-dsl-span-term-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-term-query.html
+query-dsl-span-within-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-within-query.html
+query-dsl-term-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-term-query.html
+query-dsl-terms-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-terms-query.html
+query-dsl-terms-set-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-terms-set-query.html
+query-dsl-text-expansion-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-text-expansion-query.html
+query-dsl-wildcard-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-wildcard-query.html
+query-dsl-wrapper-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-wrapper-query.html

specification/_doc_ids/table.csv

@@ -26,30 +26,62 @@ import { Id } from './common'
  * @non_exhaustive
  */
 export enum ScriptLanguage {
+  /**
+   * Painless scripting language, purpose-built for Elasticsearch.
+   */
   painless = 0,
+  /**
+   * Lucene’s expressions language, compiles a JavaScript expression to bytecode.
+   */
   expression = 1,
+  /**
+   * Mustache templated, used for templates.
+   */
   mustache = 2,
+  /**
+   * Expert Java API
+   */
   java = 3
 }
 
 export class StoredScript {
+  /**
+   * Specifies the language the script is written in.
+   */
   lang: ScriptLanguage
   options?: Dictionary<string, string>
+  /**
+   * The script source.
+   */
   source: string
 }
 
 export class ScriptBase {
+  /**
+   * Specifies any named parameters that are passed into the script as variables.
+   * Use parameters instead of hard-coded values to decrease compile time.
+   */
   params?: Dictionary<string, UserDefinedValue>
 }
 
 /** @shortcut_property source */
 export class InlineScript extends ScriptBase {
+  /**
+   * Specifies the language the script is written in.
+   * @server_default painless
+   */
   lang?: ScriptLanguage
   options?: Dictionary<string, string>
+  /**
+   * The script source.
+   */
   source: string
 }
 
 export class StoredScriptId extends ScriptBase {
+  /**
+   * The `id` for a stored script.
+   */
   id: Id
 }
 

specification/_types/Scripting.ts

@@ -265,32 +265,123 @@ export class QueryContainer {
    * @doc_id query-dsl-query-string-query
    */
   query_string?: QueryStringQuery
+  /**
+   * Returns documents that contain terms within a provided range.
+   * @doc_id query-dsl-range-query
+   */
   range?: SingleKeyDictionary<Field, RangeQuery>
+  /**
+   * Boosts the relevance score of documents based on the numeric value of a `rank_feature` or `rank_features` field.
+   * @doc_id query-dsl-rank-feature-query
+   */
   rank_feature?: RankFeatureQuery
+  /**
+   * Returns documents that contain terms matching a regular expression.
+   * @doc_id query-dsl-regexp-query
+   */
   regexp?: SingleKeyDictionary<Field, RegexpQuery>
   rule_query?: RuleQuery
+  /**
+   * Filters documents based on a provided script.
+   * The script query is typically used in a filter context.
+   * @doc_id query-dsl-script-query
+   */
   script?: ScriptQuery
+  /**
+   * Uses a script to provide a custom score for returned documents.
+   * @doc_id query-dsl-script-score-query
+   */
   script_score?: ScriptScoreQuery
+  /**
+   * Queries documents that contain fields indexed using the `shape` type.
+   * @doc_id query-dsl-shape-query
+   */
   shape?: ShapeQuery
+  /**
+   * Returns documents based on a provided query string, using a parser with a limited but fault-tolerant syntax.
+   * @doc_id query-dsl-simple-query-string-query
+   */
   simple_query_string?: SimpleQueryStringQuery
+  /**
+   * Returns matches which enclose another span query.
+   * @doc_id query-dsl-span-containing-query
+   */
   span_containing?: SpanContainingQuery
+  /**
+   * Wrapper to allow span queries to participate in composite single-field span queries by _lying_ about their search field.
+   * @doc_id query-dsl-span-field-masking-query
+   */
   field_masking_span?: SpanFieldMaskingQuery
+  /**
+   * Matches spans near the beginning of a field.
+   * @doc_id query-dsl-span-first-query
+   */
   span_first?: SpanFirstQuery
+  /**
+   * Allows you to wrap a multi term query (one of `wildcard`, `fuzzy`, `prefix`, `range`, or `regexp` query) as a `span` query, so it can be nested.
+   * @doc_id query-dsl-span-multi-term-query
+   */
   span_multi?: SpanMultiTermQuery
+  /**
+   * Matches spans which are near one another.
+   * You can specify `slop`, the maximum number of intervening unmatched positions, as well as whether matches are required to be in-order.
+   * @doc_id query-dsl-span-near-query
+   */
   span_near?: SpanNearQuery
+  /**
+   * Removes matches which overlap with another span query or which are within x tokens before (controlled by the parameter `pre`) or y tokens after (controlled by the parameter `post`) another span query.
+   * @doc_id query-dsl-span-not-query
+   */
   span_not?: SpanNotQuery
+  /**
+   * Matches the union of its span clauses.
+   * @doc_id query-dsl-span-or-query
+   */
   span_or?: SpanOrQuery
+  /**
+   * Matches spans containing a term.
+   * @doc_id query-dsl-span-term-query
+   */
   span_term?: SingleKeyDictionary<Field, SpanTermQuery>
+  /**
+   * Returns matches which are enclosed inside another span query.
+   * @doc_id query-dsl-span-within-query
+   */
   span_within?: SpanWithinQuery
+  /**
+   * Returns documents that contain an exact term in a provided field.
+   * To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.
+   * @doc_id query-dsl-term-query
+   */
   term?: SingleKeyDictionary<Field, TermQuery>
+  /**
+   * Returns documents that contain one or more exact terms in a provided field.
+   * To return a document, one or more terms must exactly match a field value, including whitespace and capitalization.
+   * @doc_id query-dsl-terms-query
+   */
   terms?: TermsQuery
+  /**
+   * Returns documents that contain a minimum number of exact terms in a provided field.
+   * To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
+   * @doc_id query-dsl-terms-set-query
+   */
   terms_set?: SingleKeyDictionary<Field, TermsSetQuery>
   /**
+   * Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a rank features field.
    * @availability stack since=8.8.0
    * @availability serverless
+   * @doc_id query-dsl-text-expansion-query
    */
   text_expansion?: SingleKeyDictionary<Field, TextExpansionQuery>
+  /**
+   * Returns documents that contain terms matching a wildcard pattern.
+   * @doc_id query-dsl-wildcard-query
+   */
   wildcard?: SingleKeyDictionary<Field, WildcardQuery>
+  /**
+   * A query that accepts any other query as base64 encoded string.
+   * @doc_id query-dsl-wrapper-query
+   */
   wrapper?: WrapperQuery
 
   /**
@@ -372,7 +463,10 @@ export class CombinedFieldsQuery extends QueryBase {
 }
 
 export class WrapperQuery extends QueryBase {
-  /** A base64 encoded query. The binary data format can be any of JSON, YAML, CBOR or SMILE encodings */
+  /**
+   * A base64 encoded query.
+   * The binary data format can be any of JSON, YAML, CBOR or SMILE encodings
+   */
   query: string
 }
 

specification/_types/query_dsl/abstractions.ts

@@ -706,37 +706,125 @@ export class QueryStringQuery extends QueryBase {
 export type SimpleQueryStringFlags = SimpleQueryStringFlag | string
 
 export enum SimpleQueryStringFlag {
+  /**
+   * Disables all operators.
+   */
   NONE = 1,
+  /**
+   * Enables the `+` AND operator.
+   */
   AND = 2,
+  /**
+   * Enables the `\|` OR operator.
+   */
   OR = 4,
+  /**
+   * Enables the `-` NOT operator.
+   */
   NOT = 8,
+  /**
+   * Enables the `*` prefix operator.
+   */
   PREFIX = 16,
+  /**
+   * Enables the `"` quotes operator used to search for phrases.
+   */
   PHRASE = 32,
+  /**
+   * Enables the `(` and `)` operators to control operator precedence.
+   */
   PRECEDENCE = 64,
+  /**
+   * Enables `\` as an escape character.
+   */
   ESCAPE = 128,
+  /**
+   * Enables whitespace as split characters.
+   */
   WHITESPACE = 256,
+  /**
+   * Enables the `~N` operator after a word, where `N` is an integer denoting the allowed edit distance for matching.
+   */
   FUZZY = 512,
+  /**
+   * Enables the `~N` operator, after a phrase where `N` is the maximum number of positions allowed between matching tokens.
+   * Synonymous to `SLOP`.
+   */
   NEAR = 1024,
+  /**
+   * Enables the `~N` operator, after a phrase where `N` is maximum number of positions allowed between matching tokens.
+   * Synonymous to `NEAR`.
+   */
   SLOP = 2048,
+  /**
+   * Enables all optional operators.
+   */
   ALL = 4096
 }
 
 export class SimpleQueryStringQuery extends QueryBase {
+  /**
+   * Analyzer used to convert text in the query string into tokens.
+   * @doc_id analysis
+   */
   analyzer?: string
-  /** @server_default false */
+  /**
+   * If `true`, the query attempts to analyze wildcard terms in the query string.
+   * @server_default false
+   */
   analyze_wildcard?: boolean
-  /** @server_default true */
+  /**
+   * If `true`, the parser creates a match_phrase query for each multi-position token.
+   * @server_default true
+   */
   auto_generate_synonyms_phrase_query?: boolean
-  /** @server_default 'or' */
+  /**
+   * Default boolean logic used to interpret text in the query string if no operators are specified.
+   * @server_default 'or'
+   */
   default_operator?: Operator
+  /**
+   * Array of fields you wish to search.
+   * Accepts wildcard expressions.
+   * You also can boost relevance scores for matches to particular fields using a caret (`^`) notation.
+   * Defaults to the `index.query.default_field index` setting, which has a default value of `*`.
+   */
   fields?: Field[]
+  /**
+   * List of enabled operators for the simple query string syntax.
+   * @server_default ALL
+   */
   flags?: SimpleQueryStringFlags
+  /**
+   * Maximum number of terms to which the query expands for fuzzy matching.
+   * @server_default 50
+   */
   fuzzy_max_expansions?: integer
+  /**
+   * Number of beginning characters left unchanged for fuzzy matching.
+   * @server_default 0
+   */
   fuzzy_prefix_length?: integer
+  /**
+   * If `true`, edits for fuzzy matching include transpositions of two adjacent characters (for example, `ab` to `ba`).
+   */
   fuzzy_transpositions?: boolean
-  /** @server_default false */
+  /**
+   * If `true`, format-based errors, such as providing a text value for a numeric field, are ignored.
+   * @server_default false
+   */
   lenient?: boolean
+  /**
+   * Minimum number of clauses that must match for a document to be returned.
+   * @doc_id query-dsl-minimum-should-match
+   */
   minimum_should_match?: MinimumShouldMatch
+  /**
+   * Query string in the simple query string syntax you wish to parse and use for search.
+   */
   query: string
+  /**
+   * Suffix appended to quoted text in the query string.
+   */
   quote_field_suffix?: string
 }