From 5dd620402011840b5a86686f630d3ae7b7616fa5 Mon Sep 17 00:00:00 2001 From: Abdon Pijpelink Date: Thu, 24 Aug 2023 14:50:19 +0200 Subject: [PATCH] [DOCS] Add descriptions for the reindex API (#2247) --- output/schema/schema.json | 137 ++++++++++++------ .../_global/reindex/ReindexRequest.ts | 50 +++++++ specification/_global/reindex/types.ts | 61 +++++++- specification/_types/common.ts | 23 +++ 4 files changed, 222 insertions(+), 49 deletions(-) diff --git a/output/schema/schema.json b/output/schema/schema.json index 2cd472add7..819b26f762 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -28678,6 +28678,7 @@ }, "properties": [ { + "description": "The name of the data stream, index, or index alias you are copying to.", "name": "index", "required": true, "type": { @@ -28689,8 +28690,10 @@ } }, { + "description": "Set to `create` to only index documents that do not already exist.\nImportant: To reindex to a data stream destination, this argument must be `create`.", "name": "op_type", "required": false, + "serverDefault": "index", "type": { "kind": "instance_of", "type": { @@ -28700,6 +28703,7 @@ } }, { + "description": "The name of the pipeline to use.", "name": "pipeline", "required": false, "type": { @@ -28711,8 +28715,10 @@ } }, { + "description": "By default, a document's routing is preserved unless it’s changed by the script.\nSet to `discard` to set routing to `null`, or `=value` to route using the specified `value`.", "name": "routing", "required": false, + "serverDefault": "keep", "type": { "kind": "instance_of", "type": { @@ -28722,6 +28728,7 @@ } }, { + "description": "The versioning to use for the indexing operation.", "name": "version_type", "required": false, "type": { @@ -28733,7 +28740,7 @@ } } ], - "specLocation": "_global/reindex/types.ts#L39-L45" + "specLocation": "_global/reindex/types.ts#L39-L64" }, { "kind": "interface", @@ -28743,6 +28750,7 @@ }, "properties": [ { + "description": "The remote connection timeout.\nDefaults to 30 seconds.", "name": "connect_timeout", "required": false, "type": { @@ -28754,6 +28762,7 @@ } }, { + "description": "An object containing the headers of the request.", "name": "headers", "required": false, "type": { @@ -28776,6 +28785,7 @@ } }, { + "description": "The URL for the remote instance of Elasticsearch that you want to index from.", "name": "host", "required": true, "type": { @@ -28787,6 +28797,7 @@ } }, { + "description": "The username to use for authentication with the remote host.", "name": "username", "required": false, "type": { @@ -28798,6 +28809,7 @@ } }, { + "description": "The password to use for authentication with the remote host.", "name": "password", "required": false, "type": { @@ -28809,6 +28821,7 @@ } }, { + "description": "The remote socket read timeout. Defaults to 30 seconds.", "name": "socket_timeout", "required": false, "type": { @@ -28820,7 +28833,7 @@ } } ], - "specLocation": "_global/reindex/types.ts#L59-L66" + "specLocation": "_global/reindex/types.ts#L99-L125" }, { "attachedBehaviors": [ @@ -28830,8 +28843,10 @@ "kind": "properties", "properties": [ { + "description": "Set to proceed to continue reindexing even if there are conflicts.", "name": "conflicts", "required": false, + "serverDefault": "abort", "type": { "kind": "instance_of", "type": { @@ -28841,6 +28856,7 @@ } }, { + "description": "The destination you are copying to.", "name": "dest", "required": true, "type": { @@ -28852,6 +28868,7 @@ } }, { + "description": "The maximum number of documents to reindex.", "name": "max_docs", "required": false, "type": { @@ -28863,6 +28880,7 @@ } }, { + "description": "The script to run to update the document source or metadata when reindexing.", "name": "script", "required": false, "type": { @@ -28885,6 +28903,7 @@ } }, { + "description": "The source you are copying from.", "name": "source", "required": true, "type": { @@ -28912,9 +28931,10 @@ "path": [], "query": [ { - "description": "Should the affected indexes be refreshed?", + "description": "If `true`, the request refreshes affected shards to make this operation visible to search.", "name": "refresh", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -28924,9 +28944,10 @@ } }, { - "description": "The throttle to set on this request in sub-requests per second. -1 means no throttle.", + "description": "The throttle for this request in sub-requests per second.\nDefaults to no throttle.", "name": "requests_per_second", "required": false, + "serverDefault": -1, "type": { "kind": "instance_of", "type": { @@ -28936,7 +28957,7 @@ } }, { - "description": "Control how long to keep the search context alive", + "description": "Specifies how long a consistent view of the index should be maintained for scrolled search.", "name": "scroll", "required": false, "type": { @@ -28948,9 +28969,10 @@ } }, { - "description": "The number of slices this task should be divided into. Defaults to 1, meaning the task isn't sliced into subtasks. Can be set to `auto`.", + "description": "The number of slices this task should be divided into.\nDefaults to 1 slice, meaning the task isn’t sliced into subtasks.", "name": "slices", "required": false, + "serverDefault": "1", "type": { "kind": "instance_of", "type": { @@ -28960,9 +28982,10 @@ } }, { - "description": "Time each individual bulk request should wait for shards that are unavailable.", + "description": "Period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards.", "name": "timeout", "required": false, + "serverDefault": "1m", "type": { "kind": "instance_of", "type": { @@ -28972,9 +28995,10 @@ } }, { - "description": "Sets the number of shard copies that must be active before proceeding with the reindex operation. Defaults to 1, meaning the primary shard only. Set to `all` for all shard copies, otherwise set to any non-negative value less than or equal to the total number of copies for the shard (number of replicas + 1)", + "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", "name": "wait_for_active_shards", "required": false, + "serverDefault": "1", "type": { "kind": "instance_of", "type": { @@ -28984,9 +29008,10 @@ } }, { - "description": "Should the request should block until the reindex is complete.", + "description": "If `true`, the request blocks until the operation is complete.", "name": "wait_for_completion", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { @@ -28996,8 +29021,10 @@ } }, { + "description": "If `true`, the destination must be an index alias.", "name": "require_alias", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -29007,7 +29034,7 @@ } } ], - "specLocation": "_global/reindex/ReindexRequest.ts#L27-L50" + "specLocation": "_global/reindex/ReindexRequest.ts#L27-L100" }, { "body": { @@ -29236,6 +29263,7 @@ }, "properties": [ { + "description": "The name of the data stream, index, or alias you are copying from.\nAccepts a comma-separated list to reindex from multiple sources.", "name": "index", "required": true, "type": { @@ -29247,6 +29275,7 @@ } }, { + "description": "Specifies the documents to reindex using the Query DSL.", "name": "query", "required": false, "type": { @@ -29258,6 +29287,7 @@ } }, { + "description": "A remote instance of Elasticsearch that you want to index from.", "name": "remote", "required": false, "type": { @@ -29269,6 +29299,7 @@ } }, { + "description": "The number of documents to index per batch.\nUse when indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB.", "name": "size", "required": false, "type": { @@ -29280,6 +29311,7 @@ } }, { + "description": "Slice the reindex request manually using the provided slice ID and total number of slices.", "name": "slice", "required": false, "type": { @@ -29303,8 +29335,10 @@ }, { "codegenName": "source_fields", + "description": "If `true` reindexes all source fields.\nSet to a list to reindex select fields.", "name": "_source", "required": false, + "serverDefault": "true", "type": { "kind": "instance_of", "type": { @@ -29325,7 +29359,7 @@ } } ], - "specLocation": "_global/reindex/types.ts#L47-L57" + "specLocation": "_global/reindex/types.ts#L66-L97" }, { "inherits": { @@ -39523,7 +39557,7 @@ "name": "AggregateName", "namespace": "_types" }, - "specLocation": "_types/common.ts#L126-L130", + "specLocation": "_types/common.ts#L137-L141", "type": { "kind": "instance_of", "type": { @@ -39785,7 +39819,7 @@ "name": "Bytes", "namespace": "_types" }, - "specLocation": "_types/common.ts#L150-L168" + "specLocation": "_types/common.ts#L161-L179" }, { "kind": "type_alias", @@ -39825,7 +39859,7 @@ "name": "ClusterInfoTarget", "namespace": "_types" }, - "specLocation": "_types/common.ts#L353-L359" + "specLocation": "_types/common.ts#L376-L382" }, { "kind": "type_alias", @@ -39833,7 +39867,7 @@ "name": "ClusterInfoTargets", "namespace": "_types" }, - "specLocation": "_types/common.ts#L361-L361", + "specLocation": "_types/common.ts#L384-L384", "type": { "items": [ { @@ -39960,9 +39994,11 @@ "kind": "enum", "members": [ { + "description": "Stop reindexing if there are conflicts.", "name": "abort" }, { + "description": "Continue reindexing even if there are conflicts.", "name": "proceed" } ], @@ -39970,7 +40006,7 @@ "name": "Conflicts", "namespace": "_types" }, - "specLocation": "_types/common.ts#L170-L173" + "specLocation": "_types/common.ts#L181-L190" }, { "kind": "interface", @@ -40491,7 +40527,7 @@ "namespace": "_types" }, "properties": [], - "specLocation": "_types/common.ts#L141-L142" + "specLocation": "_types/common.ts#L152-L153" }, { "generics": [ @@ -40684,7 +40720,7 @@ "name": "ExpandWildcard", "namespace": "_types" }, - "specLocation": "_types/common.ts#L182-L196" + "specLocation": "_types/common.ts#L199-L213" }, { "kind": "type_alias", @@ -40692,7 +40728,7 @@ "name": "ExpandWildcards", "namespace": "_types" }, - "specLocation": "_types/common.ts#L198-L198", + "specLocation": "_types/common.ts#L215-L215", "type": { "items": [ { @@ -40723,7 +40759,7 @@ "name": "Field", "namespace": "_types" }, - "specLocation": "_types/common.ts#L119-L120", + "specLocation": "_types/common.ts#L130-L131", "type": { "kind": "instance_of", "type": { @@ -41037,7 +41073,7 @@ "name": "Fields", "namespace": "_types" }, - "specLocation": "_types/common.ts#L121-L121", + "specLocation": "_types/common.ts#L132-L132", "type": { "items": [ { @@ -41132,7 +41168,7 @@ "name": "Fuzziness", "namespace": "_types" }, - "specLocation": "_types/common.ts#L114-L115", + "specLocation": "_types/common.ts#L125-L126", "type": { "items": [ { @@ -41747,7 +41783,7 @@ "name": "HealthStatus", "namespace": "_types" }, - "specLocation": "_types/common.ts#L200-L220" + "specLocation": "_types/common.ts#L217-L237" }, { "kind": "type_alias", @@ -41770,7 +41806,7 @@ "name": "HttpHeaders", "namespace": "_types" }, - "specLocation": "_types/common.ts#L139-L139", + "specLocation": "_types/common.ts#L150-L150", "type": { "key": { "kind": "instance_of", @@ -42247,7 +42283,7 @@ } } ], - "specLocation": "_types/common.ts#L307-L334" + "specLocation": "_types/common.ts#L330-L357" }, { "inherits": { @@ -42386,7 +42422,7 @@ } } ], - "specLocation": "_types/common.ts#L296-L305" + "specLocation": "_types/common.ts#L319-L328" }, { "inherits": { @@ -42627,7 +42663,7 @@ "name": "Level", "namespace": "_types" }, - "specLocation": "_types/common.ts#L230-L234" + "specLocation": "_types/common.ts#L247-L251" }, { "kind": "enum", @@ -42937,7 +42973,7 @@ "name": "MinimumShouldMatch", "namespace": "_types" }, - "specLocation": "_types/common.ts#L144-L148", + "specLocation": "_types/common.ts#L155-L159", "type": { "items": [ { @@ -42966,7 +43002,7 @@ "name": "MultiTermQueryRewrite", "namespace": "_types" }, - "specLocation": "_types/common.ts#L116-L117", + "specLocation": "_types/common.ts#L127-L128", "type": { "kind": "instance_of", "type": { @@ -43576,9 +43612,11 @@ "kind": "enum", "members": [ { + "description": "Overwrite any documents that already exist.", "name": "index" }, { + "description": "Only index documents that do not already exist.", "name": "create" } ], @@ -43586,7 +43624,7 @@ "name": "OpType", "namespace": "_types" }, - "specLocation": "_types/common.ts#L236-L239" + "specLocation": "_types/common.ts#L253-L262" }, { "kind": "type_alias", @@ -43594,7 +43632,7 @@ "name": "Password", "namespace": "_types" }, - "specLocation": "_types/common.ts#L176-L176", + "specLocation": "_types/common.ts#L193-L193", "type": { "kind": "instance_of", "type": { @@ -43763,7 +43801,7 @@ "name": "PropertyName", "namespace": "_types" }, - "specLocation": "_types/common.ts#L111-L111", + "specLocation": "_types/common.ts#L122-L122", "type": { "kind": "instance_of", "type": { @@ -44035,7 +44073,7 @@ "name": "Refresh", "namespace": "_types" }, - "specLocation": "_types/common.ts#L241-L248" + "specLocation": "_types/common.ts#L264-L271" }, { "kind": "interface", @@ -44137,7 +44175,7 @@ "name": "RelationName", "namespace": "_types" }, - "specLocation": "_types/common.ts#L112-L112", + "specLocation": "_types/common.ts#L123-L123", "type": { "kind": "instance_of", "type": { @@ -44999,7 +45037,7 @@ "name": "SearchType", "namespace": "_types" }, - "specLocation": "_types/common.ts#L250-L255" + "specLocation": "_types/common.ts#L273-L278" }, { "kind": "interface", @@ -45314,7 +45352,7 @@ "name": "SequenceNumber", "namespace": "_types" }, - "specLocation": "_types/common.ts#L109-L109", + "specLocation": "_types/common.ts#L120-L120", "type": { "kind": "instance_of", "type": { @@ -45548,7 +45586,7 @@ "name": "Slices", "namespace": "_types" }, - "specLocation": "_types/common.ts#L336-L341", + "specLocation": "_types/common.ts#L359-L364", "type": { "items": [ { @@ -45581,7 +45619,7 @@ "name": "SlicesCalculation", "namespace": "_types" }, - "specLocation": "_types/common.ts#L343-L351" + "specLocation": "_types/common.ts#L366-L374" }, { "kind": "type_alias", @@ -45977,7 +46015,7 @@ "name": "SuggestMode", "namespace": "_types" }, - "specLocation": "_types/common.ts#L257-L270" + "specLocation": "_types/common.ts#L280-L293" }, { "description": "The suggestion name as returned from the server. Depending whether typed_keys is specified this could come back\nin the form of `name#type` instead of simply `name`", @@ -45986,7 +46024,7 @@ "name": "SuggestionName", "namespace": "_types" }, - "specLocation": "_types/common.ts#L132-L136", + "specLocation": "_types/common.ts#L143-L147", "type": { "kind": "instance_of", "type": { @@ -46055,7 +46093,7 @@ "name": "TaskId", "namespace": "_types" }, - "specLocation": "_types/common.ts#L113-L113", + "specLocation": "_types/common.ts#L124-L124", "type": { "items": [ { @@ -46131,7 +46169,7 @@ "name": "ThreadType", "namespace": "_types" }, - "specLocation": "_types/common.ts#L272-L278" + "specLocation": "_types/common.ts#L295-L301" }, { "description": "Time of day, expressed as HH:MM:SS", @@ -46487,7 +46525,7 @@ "name": "Username", "namespace": "_types" }, - "specLocation": "_types/common.ts#L175-L175", + "specLocation": "_types/common.ts#L192-L192", "type": { "kind": "instance_of", "type": { @@ -46502,7 +46540,7 @@ "name": "Uuid", "namespace": "_types" }, - "specLocation": "_types/common.ts#L106-L106", + "specLocation": "_types/common.ts#L117-L117", "type": { "kind": "instance_of", "type": { @@ -46545,12 +46583,15 @@ "kind": "enum", "members": [ { + "description": "Use internal versioning that starts at 1 and increments with each update or delete.", "name": "internal" }, { + "description": "Only index the document if the given version is strictly higher than the version of the stored document or if there is no existing document.", "name": "external" }, { + "description": "Only index the document if the given version is equal or higher than the version of the stored document or if there is no existing document.\nNote: the external_gte version type is meant for special use cases and should be used with care.\nIf used incorrectly, it can result in loss of data.", "name": "external_gte" }, { @@ -46561,7 +46602,7 @@ "name": "VersionType", "namespace": "_types" }, - "specLocation": "_types/common.ts#L98-L103" + "specLocation": "_types/common.ts#L98-L114" }, { "kind": "enum", @@ -46577,7 +46618,7 @@ "name": "WaitForActiveShardOptions", "namespace": "_types" }, - "specLocation": "_types/common.ts#L280-L284" + "specLocation": "_types/common.ts#L303-L307" }, { "codegenNames": [ @@ -46589,7 +46630,7 @@ "name": "WaitForActiveShards", "namespace": "_types" }, - "specLocation": "_types/common.ts#L123-L124", + "specLocation": "_types/common.ts#L134-L135", "type": { "items": [ { @@ -46636,7 +46677,7 @@ "name": "WaitForEvents", "namespace": "_types" }, - "specLocation": "_types/common.ts#L286-L293" + "specLocation": "_types/common.ts#L309-L316" }, { "kind": "interface", diff --git a/specification/_global/reindex/ReindexRequest.ts b/specification/_global/reindex/ReindexRequest.ts index c5736bf2ae..8413591d92 100644 --- a/specification/_global/reindex/ReindexRequest.ts +++ b/specification/_global/reindex/ReindexRequest.ts @@ -30,21 +30,71 @@ import { Destination, Source } from './types' */ export interface Request extends RequestBase { query_parameters: { + /** + * If `true`, the request refreshes affected shards to make this operation visible to search. + * @server_default false + */ refresh?: boolean + /** + * The throttle for this request in sub-requests per second. + * Defaults to no throttle. + * @server_default -1 + */ requests_per_second?: float + /** + * Specifies how long a consistent view of the index should be maintained for scrolled search. + */ scroll?: Duration + /** + * The number of slices this task should be divided into. + * Defaults to 1 slice, meaning the task isn’t sliced into subtasks. + * @server_default 1 + */ slices?: Slices + /** + * Period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards. + * @server_default 1m + */ timeout?: Duration + /** + * The number of shard copies that must be active before proceeding with the operation. + * Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). + * @server_default 1 + */ wait_for_active_shards?: WaitForActiveShards + /** + * If `true`, the request blocks until the operation is complete. + * @server_default true + */ wait_for_completion?: boolean + /** + * If `true`, the destination must be an index alias. + * @server_default false + */ require_alias?: boolean } body: { + /** + * Set to proceed to continue reindexing even if there are conflicts. + * @server_default abort + */ conflicts?: Conflicts + /** + * The destination you are copying to. + */ dest: Destination + /** + * The maximum number of documents to reindex. + */ max_docs?: long + /** + * The script to run to update the document source or metadata when reindexing. + */ script?: Script size?: long + /** + * The source you are copying from. + */ source: Source } } diff --git a/specification/_global/reindex/types.ts b/specification/_global/reindex/types.ts index 2d2a99dd0f..6f49c23cf1 100644 --- a/specification/_global/reindex/types.ts +++ b/specification/_global/reindex/types.ts @@ -37,30 +37,89 @@ import { Duration } from '@_types/Time' import { Dictionary } from '@spec_utils/Dictionary' export class Destination { + /** + * The name of the data stream, index, or index alias you are copying to. + */ index: IndexName + /** + * Set to `create` to only index documents that do not already exist. + * Important: To reindex to a data stream destination, this argument must be `create`. + * @server_default index + */ op_type?: OpType + /** + * The name of the pipeline to use. + */ pipeline?: string + /** + * By default, a document's routing is preserved unless it’s changed by the script. + * Set to `discard` to set routing to `null`, or `=value` to route using the specified `value`. + * @server_default keep + */ routing?: Routing + /** + * The versioning to use for the indexing operation. + */ version_type?: VersionType } export class Source { + /** + * The name of the data stream, index, or alias you are copying from. + * Accepts a comma-separated list to reindex from multiple sources. + */ index: Indices + /** + * Specifies the documents to reindex using the Query DSL. + */ query?: QueryContainer + /** + * A remote instance of Elasticsearch that you want to index from. + */ remote?: RemoteSource + /** + * The number of documents to index per batch. + * Use when indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB. + */ size?: integer + /** + * Slice the reindex request manually using the provided slice ID and total number of slices. + */ slice?: SlicedScroll sort?: Sort - /** @codegen_name source_fields */ + /** + * If `true` reindexes all source fields. + * Set to a list to reindex select fields. + * @server_default true + * @codegen_name source_fields */ _source?: Fields runtime_mappings?: RuntimeFields } export class RemoteSource { + /** + * The remote connection timeout. + * Defaults to 30 seconds. + */ connect_timeout?: Duration + /** + * An object containing the headers of the request. + */ headers?: Dictionary + /** + * The URL for the remote instance of Elasticsearch that you want to index from. + */ host: Host + /** + * The username to use for authentication with the remote host. + */ username?: Username + /** + * The password to use for authentication with the remote host. + */ password?: Password + /** + * The remote socket read timeout. Defaults to 30 seconds. + */ socket_timeout?: Duration } diff --git a/specification/_types/common.ts b/specification/_types/common.ts index beb471dfcb..d524ee738c 100644 --- a/specification/_types/common.ts +++ b/specification/_types/common.ts @@ -96,8 +96,19 @@ export type VersionNumbers = VersionNumber[] export type VersionString = string export type VersionStrings = VersionString[] export enum VersionType { + /** + * Use internal versioning that starts at 1 and increments with each update or delete. + */ internal = 0, + /** + * Only index the document if the given version is strictly higher than the version of the stored document or if there is no existing document. + */ external = 1, + /** + * Only index the document if the given version is equal or higher than the version of the stored document or if there is no existing document. + * Note: the external_gte version type is meant for special use cases and should be used with care. + * If used incorrectly, it can result in loss of data. + */ external_gte = 2, force = 3 } @@ -168,7 +179,13 @@ export enum Bytes { } export enum Conflicts { + /** + * Stop reindexing if there are conflicts. + */ abort = 0, + /** + * Continue reindexing even if there are conflicts. + */ proceed = 1 } @@ -234,7 +251,13 @@ export enum Level { } export enum OpType { + /** + * Overwrite any documents that already exist. + */ index = 0, + /** + * Only index documents that do not already exist. + */ create = 1 }