diff --git a/modules/search/examples/about-mappings.jsonc b/modules/search/examples/about-mappings.jsonc new file mode 100644 index 000000000..ea7b45f87 --- /dev/null +++ b/modules/search/examples/about-mappings.jsonc @@ -0,0 +1,56 @@ +{ + "type": "shorthair", + "name": "British Shorthair", + "category": "shorthaired", + "origin": { + "country": "United Kingdom", + "region": "Great Britain" + }, + "physicalCharacteristics": { + "coatLength": "short", + "coatTexture": "dense", + "commonColors": [ + "blue", + "black", + "white", + "cream", + "silver" + ], + "eyeColors": [ + "copper", + "gold", + "blue", + "green" + ], + "averageWeightKg": { + "male": 6.5, + "female": 5.0 + } + }, + "temperament": [ + "calm", + "affectionate", + "independent", + "gentle" + ], + "energyLevel": "moderate", + "intelligence": "high", + "lifespanYears": { + "min": 12, + "max": 17 + }, + "careRequirements": { + "groomingFrequency": "weekly", + "sheddingLevel": "moderate", + "healthNotes": [ + "prone to obesity if overfed", + "can be predisposed to hypertrophic cardiomyopathy" + ] + }, + "goodWith": { + "children": true, + "otherCats": true, + "dogs": true + }, + "description": "The British Shorthair is a sturdy, round-faced cat known for its plush coat and easygoing personality. It is affectionate without being overly demanding and adapts well to indoor living." +} \ No newline at end of file diff --git a/modules/search/pages/about-mappings.adoc b/modules/search/pages/about-mappings.adoc new file mode 100644 index 000000000..fa7532b1b --- /dev/null +++ b/modules/search/pages/about-mappings.adoc @@ -0,0 +1,142 @@ += Map Document Collections, Objects, and Fields +:page-topic-type: concept +:description: The Search Service has distinct mapping types for collections, objects, and fields in a Search index. + +[abstract] +{description} + +Mappings control the specific documents and fields that you can return in a xref:search:run-searches.adoc[Search query]. + +You can create the following types of mappings: + +* <> +* <> +* <> +* <> + +When you create a new mapping, you need to choose whether you want a <>. + +[#collections] +== Collection Mappings + +The mapping for a collection is also called a type mapping. + +A type mapping includes or excludes specific documents in a collection from an index. +A document must match the collection and document type set by a type mapping to be included in a Search index. + +You can also choose to control the type of a document by xref:search:set-type-identifier.adoc[setting a type identifier]. +A type identifier is an optional configuration that tells the Search Service how to interpret a document's type. +Only documents that pass the filter from your type identifier can be included in your Search index under a specific type mapping, and potentially returned in search results. + +Type mappings can be <> or <>. +Add <> and <> to make a collection type mapping a static mapping. + +For more information about how to create a type mapping in the standard editor, see xref:search:create-type-mapping.adoc[]. +For more information about how to configure settings for mappings and type mappings in the Quick Editor, see xref:quick-index-field-options.adoc[]. + +=== Collection Type Mapping Names + +The Search Service uses periods (`.`) to separate collection names from xref:search:customize-index.adoc#type-identifiers[type identifiers]. +If you add a period to the name of your collection type mapping, the Search Service would interpret anything after the period as a filter value. + +For example, if you wanted to include the following document in your Search index, with a `type` value of `shorthair`: + +[source,json] +---- +include::example$about-mappings.jsonc[] +---- + +If you used a collection type mapping called `cat.breeds` and used the default *JSON type field* type identifier, the Search Service would only include documents that had a value of `breeds` in their `type` field. +That means that the British Shorthair document would not match the type mapping, and would not be included in the Search index. + +[#objects] +== Object Mappings + +Use an object mapping to add a nested JSON object from your documents to your Search index. + +For example, you would use an object mapping to add the `origin` object and its child fields to your Search index: + +[source,json] +---- +include::example$about-mappings.jsonc[lines=1..8] +---- + +Like <>, object mappings can be <> or <>. +You can add <> to make an object mapping a static type mapping. + +=== Object Names + +Avoid using an object name that contains a period (`.`) in a Search index object mapping. + +The Search Service uses periods to maintain object and child field relationships after flattening. +For example, the `country` and `region` fields inside the `origin` object would be represented as `origin.country` and `origin.region` inside your Search index: + +[source,json] +---- +include::example$about-mappings.jsonc[lines=1..8] +---- + +If you created a mapping for a field called `origin.country` as well as a `country` field mapping inside the `origin` object, the Search Service creates a single field index for both fields. +If you tried to query `origin.country` in a Search query with an analyzer, the Search Service would fail to pick the right analyzer for the `origin.country` field because of the 2 overlapping mappings. +This can cause undesired or unexpected search results. + +To avoid issues with overlapping field and object names in a Search index, do not use periods (`.`) in your JSON document field or object names. + +[#fields] +== Child Field Mappings + +Use a child field mapping to add a specific document field from your documents to your Search index. + +A child field mapping can exist at the top-level of your document hierarchy and be created directly under a <>, or it can exist as a nested field underneath an <> or <>. + +Use a child field mapping to turn a parent mapping into a static mapping. + +For example, you could create a child field mapping for the `type`, `name`, and `category` fields underneath the collection type mapping for this document. +You could also create a child field mapping under the object mapping for the `origin` object for the `country` and `region` fields: + +[source,json] +---- +include::example$about-mappings.jsonc[lines=1..8] +---- + +Just like <>, to avoid undesired results in your Search queries, avoid using periods (`.`) in your child field names. +See <> for examples and an explanation. + +[#xattrs] +== XATTRs Mappings + +IMPORTANT: You can only use XATTRs mappings on Couchbase Server version 7.6.2 or later. + +Extended Attributes (XATTRs) mappings add fields and metadata from your document's XATTRs and let you query them inside a Search index. + +XATTRs mappings can be <> or <>, based on whether you add <>. + +Just like <> and <>, to avoid undesired results in your Search queries, avoid using periods (`.`) in the names of fields in your document metadata. +See <> for examples and an explanation. + +[#static-vs-dynamic] +== Choosing a Static or Dynamic Mapping + +Each mapping type can be either *static* or *dynamic*: + +[[static]]Static mappings:: When your data fields are stable and unlikely to change, use a static type mapping to add and define only specific fields from a matching document type to an index. +If you're unsure about your document structure and how it might change, use <>, instead. ++ +For example, you could create a static type mapping to only include the contents of the `description` field from the `cats` collection in your Search index, as a text field with an `en` analyzer. ++ +Add <> to a <>, <>, or <> to make it static. +Or, in the xref:create-quick-index.adoc[Quick Editor], click a document field in your document schema to create a static type mapping. + +[[dynamic]]Dynamic mappings:: When you do not know the structure of your data fields ahead of time, use a dynamic type mapping to add all available fields from a matching document type, collection, or JSON object to an index. +If your document structure is more stable and unlikely to change, use <> to get the best results from the Search Service. ++ +For example, you could create a dynamic type mapping to include all documents from a `cats` collection in your Search index, or include all fields under the `careRequirements` object from a document schema. + + +== See Also + +* xref:set-type-identifier.adoc[] +* xref:create-type-mapping.adoc[] +* xref:create-child-mapping.adoc[] +* xref:create-child-field.adoc[] +* xref:create-xattrs-mapping.adoc[] \ No newline at end of file diff --git a/modules/search/pages/create-child-mapping.adoc b/modules/search/pages/create-child-mapping.adoc index 94ef986cc..ea7c65f7c 100644 --- a/modules/search/pages/create-child-mapping.adoc +++ b/modules/search/pages/create-child-mapping.adoc @@ -33,7 +33,7 @@ To create a child mapping with the Couchbase {page-ui-name}: . In the *{}* field, enter the name of a field in a document that contains a JSON object. . (Optional) To only index the fields you add to the child mapping, select *only index specified fields*. + -Otherwise, your child mapping is a xref:customize-index.adoc#type-mappings[dynamic mapping] that includes all child fields of the JSON object. +Otherwise, your child mapping is a xref:about-mmapings.adoc#dynamic[dynamic mapping] that includes all child fields of the JSON object. . (Optional) To set a different analyzer for the child mapping, in the *Analyzer* list, select an analyzer. + You can select a xref:default-analyzers-reference.adoc[default analyzer] or xref:create-custom-analyzer.adoc[create your own]. diff --git a/modules/search/pages/create-search-index-rest-api.adoc b/modules/search/pages/create-search-index-rest-api.adoc index f99844426..399fb3194 100644 --- a/modules/search/pages/create-search-index-rest-api.adoc +++ b/modules/search/pages/create-search-index-rest-api.adoc @@ -58,7 +58,7 @@ For more information about how to create an index with the UI, see xref:create-s === Example: Simple Search Index with XATTRs In the following example, the JSON payload creates a simple index named `landmark-content-index` on the `travel-sample` bucket. -It creates a type mapping for the `inventory.landmark` collection, with a child field, `content`, and adds a dynamic Extended Attributes (XATTRs) mapping for any available document metadata fields in the collection: +It creates a type mapping for the `inventory.landmark` collection, with a child field, `content`, and adds a xref:about-mappings.adoc#xattrs[dynamic Extended Attributes (XATTRs) mapping] for any available document metadata fields in the collection: [source,console] ---- diff --git a/modules/search/pages/create-type-mapping.adoc b/modules/search/pages/create-type-mapping.adoc index 4642a493b..02b49a5dd 100644 --- a/modules/search/pages/create-type-mapping.adoc +++ b/modules/search/pages/create-type-mapping.adoc @@ -7,7 +7,7 @@ [abstract] {description} -For more information, see xref:customize-index.adoc#type-mappings[Customize a Search Index with the Web Console]. +For more information, see xref:about-mappings.adoc#collections[Collection Mappings]. == Prerequisites @@ -39,7 +39,7 @@ For more information, see xref:set-type-identifier.adoc[]. . (Optional) To use a specific analyzer for documents in the type mapping, in the *Analyzer* list, select an analyzer. + You can xref:default-analyzers-reference.adoc[use a default analyzer] or xref:create-custom-analyzer.adoc[create your own]. -. (Optional) To switch from a xref:customize-index.adoc#type-mappings[dynamic type mapping to a static type mapping], select *Only index specified fields*. +. (Optional) To switch from a xref:about-mappings.adoc#dynamic[dynamic type mapping] to a xref:about-mappings.adoc#static[static type mapping], select *Only index specified fields*. .. To choose which fields to add or remove from the static type mapping, see xref:create-child-field.adoc[]. .. To add a child mapping for a document field that contains a JSON object, see xref:create-child-mapping.adoc[]. . (Optional) To remove all documents that match the type mapping from your Search index, clear the checkbox for that type mapping. diff --git a/modules/search/pages/create-xattrs-mapping.adoc b/modules/search/pages/create-xattrs-mapping.adoc index 836221d81..311c0ec8e 100644 --- a/modules/search/pages/create-xattrs-mapping.adoc +++ b/modules/search/pages/create-xattrs-mapping.adoc @@ -7,7 +7,8 @@ [abstract] {description} -You must add an XATTRs mapping to your Search index to use and search for XATTRs metadata in your documents. +You must add an XATTRs mapping to your Search index to use and search for XATTRs metadata in your documents. +For more information about the different mapping types for the Search Service, see xref:about-mappings.adoc[]. == Prerequisites @@ -37,7 +38,7 @@ To add an XATTRs mapping to your Search index from the {page-ui-name}: . Click *insert xattrs mapping*. . (Optional) To only index the fields you add to the XATTRs mapping, select *only index specified fields*. + -Otherwise, your XATTRs mapping is a xref:customize-index.adoc#type-mappings[dynamic mapping] that includes all child fields from your documents' metadata. +Otherwise, your XATTRs mapping is a xref:about-mappings.adoc#dynamic[dynamic mapping] that includes all child fields from your documents' metadata. . (Optional) To set a different analyzer for the XATTRs mapping, in the *Analyzer* list, select an analyzer. + You can select a xref:default-analyzers-reference.adoc[default analyzer] or xref:create-custom-analyzer.adoc[create your own]. diff --git a/modules/search/pages/customize-index.adoc b/modules/search/pages/customize-index.adoc index e1a429998..12649285a 100644 --- a/modules/search/pages/customize-index.adoc +++ b/modules/search/pages/customize-index.adoc @@ -35,35 +35,7 @@ For more information about how to configure a type identifier, see xref:set-type |✓ |✓ a|Use a type mapping to include or exclude specific documents in a collection from an index. - -Type mappings can also set a document field's data type and other settings. - -You can create two types of type mappings with the Search Service: - -* *Dynamic type mappings*: When you do not know the structure of your data fields ahead of time, use a dynamic type mapping to add all available fields from a matching document type to an index. -For example, you could create a dynamic type mapping to include all documents from the `hotel` collection in your Search index, or include all fields under a JSON object from your document schema. -+ -Configure this type of mapping by selecting a collection in xref:create-quick-index.adoc[the Quick Editor] or by clearing *Only index specified fields* when you xref:create-type-mapping.adoc[]. - -* *Static type mappings*: When your data fields are stable and unlikely to change, use a static type mapping to add and define only specific fields from a matching document type to an index. -For example, you could create a static type mapping to only include the contents of the `city` field from the `hotel` collection in your Search index, as a text field with an `en` analyzer. -+ -Configure this type of mapping by selecting a field in your document schema in xref:create-quick-index.adoc[the Quick Editor]. -+ -In the standard editor, xref:create-type-mapping.adoc[create a type mapping] and xref:create-child-field.adoc[add a child field mapping] to create a static type mapping. - -Type mappings start at the collection level. -Create additional mappings for child fields or xref:create-child-mapping.adoc[JSON objects] under a collection's type mapping to restrict the documents added to your index. -This can improve Search index performance over indexing entire collections. - -For a type mapping defined on a scope and collection, you can add an additional filter known as a <>, to restrict the documents included from a type mapping. -Only documents from your specified scope and collection that also pass the type identifier's filter can be included in your Search index, and potentially returned in search results. - -If your cluster is running Couchbase Server version 7.6.2 and later, you can also choose to include document metadata inside your Search index by xref:create-xattrs-mapping.adoc[creating an XATTRs mapping]. - -For more information about how to configure settings for mappings and type mappings in the Quick Editor, see xref:quick-index-field-options.adoc[]. - -For more information about how to configure a type mapping in the standard editor, see xref:create-type-mapping.adoc[]. +For more information about the different kinds of mappings in a Search index, see xref:about-mappings.adoc[]. |[[analyzers]]Analyzers | diff --git a/modules/search/pages/field-data-types-reference.adoc b/modules/search/pages/field-data-types-reference.adoc index 6ffbc595b..66cb96d40 100644 --- a/modules/search/pages/field-data-types-reference.adoc +++ b/modules/search/pages/field-data-types-reference.adoc @@ -10,7 +10,7 @@ When you xref:create-child-field.adoc[create a child field] on a type mapping or xref:create-quick-index.adoc[], you need to set a field's data type. If you create a Search index and do not set a data type for a field, the Search Service automatically assigns a field data type. -For example, if you created a xref:customize-index.adoc#type-mappings[dynamic type mapping], the Search Service automatically assigns data types to all fields in the type mapping. +For example, if you created a xref:about-mappings.adoc#dynamic[dynamic type mapping], the Search Service automatically assigns data types to all fields in the type mapping. The following field data types are available: diff --git a/modules/search/pages/search-index-params.adoc b/modules/search/pages/search-index-params.adoc index 58208d7f5..4bfbefd9b 100644 --- a/modules/search/pages/search-index-params.adoc +++ b/modules/search/pages/search-index-params.adoc @@ -160,7 +160,7 @@ The number of replicas you can create depends on the number of nodes you have av [#params] == Params Object -The `params` object sets a Search index's xref:customize-index.adoc#type-identifiers[type identifier], xref:customize-index.adoc#type-mappings[type mappings], and xref:customize-index.adoc#analyzers[analyzers]. +The `params` object sets a Search index's xref:customize-index.adoc#type-identifiers[type identifier], xref:about-mappings.adoc[type mappings], and xref:customize-index.adoc#analyzers[analyzers]. It contains the following properties: @@ -1435,7 +1435,7 @@ TIP: To add a type identifier as an additional filter to your type mapping, add [#scope-collection] === \{Scope\}.\{collection\} Objects, JSON Object Field Objects, and XATTRs Objects -The `\{scope\}.\{collection\}` object defines a custom type mapping for a Search index, on a specific scope and collection in the cluster: +The `\{scope\}.\{collection\}` object defines a xref:about-mappings.adoc[custom type mapping] for a Search index, on a specific scope and collection in the cluster: [source,json] ---- @@ -1460,7 +1460,7 @@ If your cluster is running Couchbase Server version 7.6.2 and later, and you're * Use the same property structure as a `\{scope\}.\{collection\}` object. For example, the following JSON index definition snippet defines a `\{scope\}.\{collection\}` object for the `inventory.hotel` scope and collection. -It adds a dynamic mapping for any XATTRs metadata present on documents in the collection. +It adds a xref:about-mappings.adoc#dynamic[dynamic mapping] for any XATTRs metadata present on documents in the collection. It adds two nested JSON Object Field objects, `reviews` and `ratings`, that contain a single <> for the `Cleanliness` field: [source,json] @@ -1480,10 +1480,10 @@ For more information, see xref:manage:manage-documents/manage-documents.adoc[]. |dynamic |Boolean |Yes a| To index all fields under the specified scope and collection, JSON object, or all fields inside XATTRs, set `dynamic` to `true`. -This creates a xref:customize-index.adoc#type-mappings[dynamic type mapping]. +This creates a xref:about-mappings.adoc#dynamic[dynamic type mapping]. To only index the fields you specify and enable the `properties` block, set `dynamic` to `false`. -This creates a xref:customize-index.adoc#type-mappings[static type mapping]. +This creates a xref:about-mappings.adoc#static[static type mapping]. |enabled |Boolean |Yes a| diff --git a/modules/search/pages/set-advanced-settings.adoc b/modules/search/pages/set-advanced-settings.adoc index eb55f3a70..6ff7bd5f4 100644 --- a/modules/search/pages/set-advanced-settings.adoc +++ b/modules/search/pages/set-advanced-settings.adoc @@ -76,11 +76,11 @@ You can add fields to the `_all` field to search their contents without specifyi Enter a value in the *Default Field* field to change the name of this default field. -|Store Dynamic Fields |Select *Store Dynamic Fields* to include field values in search results from a xref:customize-index.adoc#type-mappings[dynamic type mapping] in the index. +|Store Dynamic Fields |Select *Store Dynamic Fields* to include field values in search results from a xref:about-mappings.adoc#dynamic[dynamic type mapping] in the index. -|Index Dynamic Fields |Select *Index Dynamic Fields* to include fields from a xref:customize-index.adoc#type-mappings[dynamic type mapping] in the index. +|Index Dynamic Fields |Select *Index Dynamic Fields* to include fields from a xref:about-mappings.adoc#dynamic[dynamic type mapping] in the index. -|DocValues for Dynamic Fields |Select *DocValues for Dynamic Fields* to include the values of each field from a xref:customize-index.adoc#type-mappings[dynamic type mapping] in the index for xref:search-request-params.adoc#facets[Facets] and sorting search results. +|DocValues for Dynamic Fields |Select *DocValues for Dynamic Fields* to include the values of each field from a xref:about-mappings.adoc#dynamic[dynamic type mapping] in the index for xref:search-request-params.adoc#facets[Facets] and sorting search results. |Index Replicas a| diff --git a/modules/search/partials/nav.adoc b/modules/search/partials/nav.adoc index cae2c9da5..e23302cac 100644 --- a/modules/search/partials/nav.adoc +++ b/modules/search/partials/nav.adoc @@ -27,12 +27,13 @@ *** xref:search:create-search-index-alias.adoc[] *** xref:search:create-search-index-alias-rest-api.adoc[] ** xref:search:customize-index.adoc[] - *** xref:search:set-type-identifier.adoc[] - *** xref:search:create-type-mapping.adoc[] - *** xref:search:create-child-field.adoc[] - **** xref:search:child-field-options-reference.adoc[] - *** xref:search:create-child-mapping.adoc[] - *** xref:search:create-xattrs-mapping.adoc[] + *** xref:search:about-mappings.adoc[] + **** xref:search:set-type-identifier.adoc[] + **** xref:search:create-type-mapping.adoc[] + **** xref:search:create-child-field.adoc[] + ***** xref:search:child-field-options-reference.adoc[] + **** xref:search:create-child-mapping.adoc[] + **** xref:search:create-xattrs-mapping.adoc[] *** xref:search:create-custom-analyzer.adoc[] *** xref:search:create-custom-character-filter.adoc[] *** xref:search:create-custom-tokenizer.adoc[]