[DOC-13923] Clarify Behaviour When Field Names Contain Periods

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."
+}

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: 
+
+* <<collections,>>
+* <<objects,>>
+* <<fields,>>
+* <<xattrs,>>
+
+When you create a new mapping, you need to choose whether you want a <<static-vs-dynamic,Static or Dynamic Mapping>>.
+
+[#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 <<static,>> or <<dynamic,>>.
+Add <<objects,>> and <<fields,>> 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 <<collections,>>, object mappings can be <<static,static>> or <<dynamic,dynamic>>.
+You can add <<fields,>> 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 <<collections,collection type mapping>>, or it can exist as a nested field underneath an <<objects,object mapping>> or <<xattrs,XATTRs mapping>>.
+
+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 <<object-names,>>, to avoid undesired results in your Search queries, avoid using periods (`.`) in your child field names.
+See <<object-names,>> 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 <<static,static>> or <<dynamic,dynamic>>, based on whether you add <<fields,>>.
+
+Just like <<object-names,>> and <<fields,>>, to avoid undesired results in your Search queries, avoid using periods (`.`) in the names of fields in your document metadata.
+See <<object-names,>> 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 <<dynamic,>>, 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 <<fields,>> to a <<collections,collection type mapping>>, <<objects,object mapping>>, or <<xattrs,XATTRs mapping>> 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 <<static,>> 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[]

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]. 

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]
 ----

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. 

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]. 

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 <<type-identifiers,type identifier>>, 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 
 |

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: 
 

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 <<child-fields,child field object>> 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|