diff --git a/modules/search/examples/create-search-index-payload-filters.sh b/modules/search/examples/create-search-index-payload-filters.sh new file mode 100644 index 00000000..0b5fffce --- /dev/null +++ b/modules/search/examples/create-search-index-payload-filters.sh @@ -0,0 +1,151 @@ +curl -s -XPUT -H "Content-Type: application/json" \ + -u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/bucket/travel-sample/scope/inventory/index/travel-sample-filter-index + -d \ + '{ + "type": "fulltext-index", + "name": "travel-sample.inventory.travel-sample-filter", + "sourceType": "gocbcore", + "sourceName": "travel-sample", + "planParams": { + "maxPartitionsPerPIndex": 128, + "indexPartitions": 1 + }, + "params": { + "doc_config": { + "doc_filter": { + "cleanliness_AND_free_breakfast": { + "conjuncts": [ + { + "field": "reviews.ratings.Cleanliness", + "inclusive_max": true, + "max": 5, + "min": 3 + }, + { + "bool": true, + "field": "free_breakfast" + } + ], + "order": 1 + } + }, + "docid_prefix_delim": "", + "docid_regexp": "", + "mode": "scope.collection.custom", + "type_field": "type" + }, + "mapping": { + "analysis": {}, + "default_analyzer": "standard", + "default_datetime_parser": "dateTimeOptional", + "default_field": "_all", + "default_mapping": { + "dynamic": true, + "enabled": false + }, + "default_type": "_default", + "docvalues_dynamic": false, + "index_dynamic": true, + "store_dynamic": false, + "type_field": "_type", + "types": { + "inventory.hotel.cleanliness_AND_free_breakfast": { + "dynamic": false, + "enabled": true, + "properties": { + "description": { + "dynamic": false, + "enabled": true, + "fields": [ + { + "docvalues": true, + "include_in_all": true, + "include_term_vectors": true, + "index": true, + "name": "description", + "store": true, + "type": "text" + } + ] + }, + "free_breakfast": { + "dynamic": false, + "enabled": true, + "fields": [ + { + "docvalues": true, + "include_in_all": true, + "index": true, + "name": "free_breakfast", + "store": true, + "type": "boolean" + } + ] + }, + "name": { + "dynamic": false, + "enabled": true, + "fields": [ + { + "docvalues": true, + "include_in_all": true, + "include_term_vectors": true, + "index": true, + "name": "name", + "store": true, + "type": "text" + } + ] + }, + "reviews": { + "dynamic": false, + "enabled": true, + "properties": { + "content": { + "dynamic": false, + "enabled": true, + "fields": [ + { + "docvalues": true, + "include_in_all": true, + "include_term_vectors": true, + "index": true, + "name": "content", + "store": true, + "type": "text" + } + ] + }, + "ratings": { + "dynamic": false, + "enabled": true, + "properties": { + "Cleanliness": { + "dynamic": false, + "enabled": true, + "fields": [ + { + "docvalues": true, + "include_in_all": true, + "index": true, + "name": "Cleanliness", + "store": true, + "type": "number" + } + ] + } + } + } + } + } + } + } + } + }, + "store": { + "indexType": "scorch", + "segmentVersion": 16 + } + }, + "sourceParams": {} + }' \ No newline at end of file diff --git a/modules/search/examples/create-search-index-response-filters.json b/modules/search/examples/create-search-index-response-filters.json new file mode 100644 index 00000000..0ae7c552 --- /dev/null +++ b/modules/search/examples/create-search-index-response-filters.json @@ -0,0 +1,5 @@ +{ + "status": "ok", + "name": "travel-sample.inventory.travel-sample-filter-index", + "uuid": "5454607bd6b4b3e1" +} \ No newline at end of file diff --git a/modules/search/examples/simple-search-index-payload.jsonc b/modules/search/examples/simple-search-index-payload.jsonc index e87deb45..53bf8a1e 100644 --- a/modules/search/examples/simple-search-index-payload.jsonc +++ b/modules/search/examples/simple-search-index-payload.jsonc @@ -20,8 +20,78 @@ "doc_config": { "docid_prefix_delim": "", "docid_regexp": "", - "mode": "scope.collection.type_field", - "type_field": "type" + "mode": "scope.collection.custom", + "type_field": "type", + // tag::doc_filter[] + "doc_filter": { + // tag::boolean_filter[] + "free_breakfast_true": { + "bool": true, + "field": "free_breakfast", + "order": 1 + }, + // end::boolean_filter[] + // tag::date_range_filter[] + "review_date_range": { + "start": "2015-01-01", + "end": "2019-01-01", + "inclusive_end": true, + "inclusive_start": false, + "field": "reviews.date", + "order": 2, + "datetime_parser": "My_Date_Time_Parser" + }, + // end::date_range_filter[] + // tag::numeric_range_filter[] + "cleanliness_range": { + "min": 3, + "max": 5, + "inclusive_min": true, + "inclusive_max": true, + "field": "reviews.ratings.Cleanliness", + "order": 3 + }, + // end::numeric_range_filter[] + // tag::conjunct_filter[] + "free_parking_AND_vacancy": { + "conjuncts": [ + { + "bool": true, + "field": "vacancy" + }, + { + "bool": true, + "field": "free_parking" + } + ], + "order": 4 + }, + // end::conjunct_filter[] + // tag::disjunct_filter[] + "location_OR_service": { + "disjuncts": [ + { + "min": 5, + "field": "reviews.ratings.Service" + }, + { + "min": 5, + "field": "reviews.ratings.Location" + } + ], + "order": 6 + }, + // end::disjunct_filter[] + // tag::term_filter[] + "name_hotel": { + "term": "Hotel", + "order": 5, + "field": "name" + } + // end::term_filter[] + + } + // end::doc_filter[] }, // end::doc_config[] // tag::mapping[] @@ -194,6 +264,26 @@ ] } } + }, + "inventory.hotel.free_breakfast_true": { + "dynamic": true, + "enabled": true, + "properties": { + "free_breakfast": { + "dynamic": false, + "enabled": true, + "fields": [ + { + "docvalues": true, + "include_in_all": true, + "index": true, + "name": "free_breakfast", + "store": true, + "type": "boolean" + } + ] + } + } } // end::scope_collection[] } diff --git a/modules/search/pages/create-search-index-rest-api.adoc b/modules/search/pages/create-search-index-rest-api.adoc index 3589a43d..809e8191 100644 --- a/modules/search/pages/create-search-index-rest-api.adoc +++ b/modules/search/pages/create-search-index-rest-api.adoc @@ -55,7 +55,7 @@ Do not include the xref:search-index-params.adoc#uuid[uuid] or xref:search-index TIP: If you remove the xref:search-index-params.adoc#uuid[uuid] and xref:search-index-params.adoc#sourceuuid[sourceUUID] parameters, you can copy the Search index definition JSON payload from the Couchbase {page-ui-name} to use in your REST API call. For more information about how to create an index with the UI, see xref:create-search-index-ui.adoc[]. -=== Example +=== 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: @@ -79,6 +79,33 @@ include::example$create-search-index-response.json[] The `"uuid"` is randomly generated for each Search index you create. Your own UUID might not match the value shown in the example. +=== Example: Search Index with Custom Document Filter + +[.status]#Couchbase Server 8.0# + +In the following example, the JSON payload creates a Search index named `travel-sample-filter` on the `travel-sample` bucket. +It has a custom document filter, `cleanliness_AND_free_breakfast`, which uses a xref:search-index-params.adoc#conjunct_filter[conjunct filter] to restrict the documents in the index. +Only documents with a cleanliness rating between 3 and 5 and `free_breakfast` set to `true` are included from the `inventory.hotel` collection. + +For documents that pass the filter, the index includes the `description`, `free_breakfast`, `name`, `reviews.content`, and `reviews.ratings.Cleanliness` fields: + +[source,console] +---- +include::example$create-search-index-payload-filters.sh[] +---- + +For more information about the available JSON properties for a Search index, see xref:search-index-params.adoc[]. + +If the REST API call is successful, the Search Service returns a `200 OK` and the following JSON response: + +[source,json] +---- +include::example$create-search-index-response-filters.json[] +---- + +The `"uuid"` is randomly generated for each Search index you create. +Your own UUID might not match the value shown in the example. + == Next Steps After you create a Search index, you can xref:simple-search-rest-api.adoc[] to test your Search index. diff --git a/modules/search/pages/create-type-mapping.adoc b/modules/search/pages/create-type-mapping.adoc index 7f863b55..a11cbd84 100644 --- a/modules/search/pages/create-type-mapping.adoc +++ b/modules/search/pages/create-type-mapping.adoc @@ -31,9 +31,10 @@ To create a type mapping with the Couchbase {page-ui-name}: . Do one of the following: .. If you selected *Use non-default scope/collection(s)*, in the *Collection* list, select the collection where you want to create the type mapping. .. If you cleared *Use non-default scope/collection(s)*, in the *#* field, enter the name of a type field where you want to create a type mapping. -. (Optional) To only include documents of a specific type from a collection, add the document type to the end of the collection in the *#* field. +. (Optional) To only include documents from a collection based on a specific filter, add the name of the filter or the filter value to the end of the collection in the *#* field. ++ +For example, `inventory.hotel.free_breakfast_true` or `inventory.hotel.hotel`. + -For example, `scope.collection.document_type`. 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. + diff --git a/modules/search/pages/customize-index.adoc b/modules/search/pages/customize-index.adoc index 149d24ee..4ac11ccc 100644 --- a/modules/search/pages/customize-index.adoc +++ b/modules/search/pages/customize-index.adoc @@ -19,11 +19,15 @@ You can add the following components and configure the following options for a S |[[type-identifiers]]Type Identifier | |✓ -a|Set a type identifier to add a filter to the documents added to your Search index: +a|Set a type identifier to add a filter to the documents added to your Search index through a <>: * JSON Type Field: Selects only documents that contain a specific field with a specified string value. * Doc ID up to Separator: Selects only documents with an ID or key up to a specific substring. * Doc ID with Regex: Selects only documents with an ID or key that matches a regular expression. +* [.status]#Couchbase Server 8.0# Custom: As of Couchbase Server version 8.0, custom document filters select only documents that match a custom filter, based on the values of specific fields. + +Type identifiers add a more granular filter to the documents in a type mapping. +If a type mapping has a type identifier, only documents that match the type identifier can be included in the Search index. For more information about how to configure a type identifier, see xref:set-type-identifier.adoc[]. @@ -32,7 +36,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 field's data type and other settings. +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: @@ -52,6 +56,9 @@ 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[]. diff --git a/modules/search/pages/search-index-params.adoc b/modules/search/pages/search-index-params.adoc index b7702939..ff9be834 100644 --- a/modules/search/pages/search-index-params.adoc +++ b/modules/search/pages/search-index-params.adoc @@ -157,13 +157,15 @@ The `doc_config` object is a child object of the <>. It contains the fo |mode |String |Yes a| -Set a xref:customize-index.adoc#type-identifiers[type identifier] for the Search index to filter documents from search results: +Set a xref:customize-index.adoc#type-identifiers[type identifier] for the Search index to filter documents. +Set the mode for your type identifier by setting this property to `"scope.collection.\{mode\}"` +You can choose from one of the following mode values: * `type_field`: Use the value from a specific field in the documents. * `docid_prefix_delim`: Use the leading characters in the documents' ID values, up to but not including a specified separator. * `docid_regexp`: Use a regular expression on the documents' ID values. - -NOTE: If you want your Search index to only include documents from a specific collection, the `mode` value must be `"scope.collection.\{mode\}"`. +* `custom`: Use a custom document filter expression to filter documents based on specific values. +See <>. |docid_prefix_delim |String |Yes a| @@ -171,11 +173,25 @@ If `mode` is `docid_prefix_delim`, set the separator character to use on a docum For example, to filter documents based on the characters before a `\_` in their ID values, set `docid_prefix_delim` to `_`. +To use this filter later, you need to modify the name of the type mapping where you want to use the filter. + +For example, you could set a specific filter value of `hotel` on a type mapping. +If `docid_prefix_delim` is set to `\_`, a document would have to have the string `hotel` before the character `_` in its ID value to pass the filter. +To use the filter, set the <> name to `\{scope\}.\{collection\}.hotel`. +If the document passes the filter, it's included in the type mapping, and your Search index. + |docid_regexp |String |Yes a| If `mode` is `docid_regexp`, set the regular expression to use on a document's ID value to determine its type. -For example, to filter documents that contain the characters `\_40` in their ID value, set `docid_regexp` to `_[3-5]0`. +For example, to filter documents that contain the characters `\_40` in their ID value, set `docid_regexp` to `_[3-5]0`. + +To use this filter later, you need to modify the name of the type mapping where you want to use the filter. + +For example, you could set a specific filter value of `_40` on a type mapping. +A document with the characters `_40` in its ID value would pass the filter. +To use the filter, set the <> name to `\{scope\}.\{collection\}._40`. +If the document passes the filter, it's included in the type mapping, and your Search index. |type_field |String |Yes a| @@ -183,6 +199,377 @@ If `mode` is `type_field`, set the name of the field to use to filter documents. For example, to filter documents based on the value of their `type` field, set `type_field` to `type`. +To use this filter later, you need to modify the name of the type mapping where you want to use the filter. + +For example, you could use a field called `type` as your `type_field`. +A document could have to have `landmark` in its `type` field to pass the filter. +To use the filter, set your <> name to `\{scope\}.\{collection\}.landmark`. + +|[[doc_filter]]doc_filter |Object |Yes a| + +[.status]#Couchbase Server 8.0# + +If `mode` is `custom`, provide an object that sets a custom document filter for a scope and collection in your Search index. + +You can filter documents with custom filters based on the value of: + +* <>. +* <>. +* <>. +* <>. +* A <> or <> object that combines 2 or more of the available filters. + +You can add up to a maximum of 100 document filters on a single Search index. + +For more information about how to define each type of filter in your Search index definition, see <>. + +|==== + +[#doc_filter_obj] +==== Doc_filter Object + +[.status]#Couchbase Server 8.0# + +The `doc_filter` object contains JSON objects for each document filter you want to apply to a type mapping in your Search index: + +[source,json] +---- +include::example$simple-search-index-payload.jsonc[tag=doc_filter] +---- + +TIP: To view the entire JSON payload, click btn:[View]. + +You can add up to a maximum of 100 document filters on a single Search index. + +You can define the following types of document filters: + +* <> +* <> +* <> +* <> +* <> +* <> + +[#boolean_filter] +===== Boolean Document Filters + +[.status]#Couchbase Server 8.0# + +A boolean document filter adds or removes documents from a type mapping based on the value of a boolean field: + +[source,json] +---- +include::example$simple-search-index-payload.jsonc[tag=boolean_filter] +---- + +TIP: To view the entire JSON payload, click btn:[View]. + +Set the name of your boolean document filter object to the name you want for your filter. +Use this name to use the filter on a <>. +For example, `\{scope\}.\{collection\}.free_breakfast_true`. + +A boolean document filter can have the following properties: + +[cols="2,1,1,4"] +|==== +|Property |Type |Required? |Description + +|bool |Boolean |Yes a| + +Set `bool` to the value a document must have in your chosen boolean field for a document to pass the filter. + +`bool` can be `true` or `false`. + +|field |String |Yes a| + +Enter the name of the field that contains a boolean value you want to use as a filter. + +|order |Number |Yes a| + +include::partial$order-doc-filter-description.adoc[] + +|==== + +[#date_range_filter] +===== Date Range Document Filters + +[.status]#Couchbase Server 8.0# + +A date range document filter adds or removes documents from a type mapping based on the value of a date field and a specified range: + +[source,json] +---- +include::example$simple-search-index-payload.jsonc[tag=date_range_filter] +---- + +TIP: To view the entire JSON payload, click btn:[View]. + +Set the name of your date range document filter object to the name you want for your filter. +Use this name to use the filter on a <>. +For example, `\{scope\}.\{collection\}.review_date_range`. + +A date range document filter can have the following properties: + +[cols="2,1,1,4"] +|==== +|Property |Type |Required? |Description + +|start |Date and Time String |No a| + +Set the start date for the range you want to use as a filter. +Dates occurring before your `start` value do not pass the filter. + +You can choose to set only a `start` value or only an `end` value for the filter. + +By default, the value for `start` is included in your date range filter. + +|end |Date and Time String |No a| + +Set the end date for the range you want to use as a filter. +Dates occurring after your `end` value do not pass the filter. + +You can choose to set only a `start` value or only an `end` value for the filter. + +By default, the value for `end` is excluded from your date range filter. + +|inclusive_start |Boolean |No a| + +Set whether the value of `start` should be included or excluded from the range: + +* If `inclusive_start` is `true`, documents with the same date and time string as `start` pass the filter. +* If `inclusive_start` is `false`, documents must have a date and time string that's later than the value of `start` to pass the filter. + +If you do not set a value for `inclusive_start`, by default, `start` is inclusive to your date range. + +|inclusive_end |Boolean |No a| + +Set whether the value of `end` should be included or excluded from the range: + +* If `inclusive_end` is `true`, documents with the same date and time string as `end` pass the filter. +* If `inclusive_end` is `false`, documents must have a date and time string that's earlier than the value of `end` to pass the filter. + +If you do not set a value for `inclusive_end`, by default, `end` is not included in your date range. + +|field |String |Yes a| + +Enter the name of the field that contains a date value you want to use as a filter. + +|order |Number |Yes a| + +include::partial$order-doc-filter-description.adoc[] + +|datetime_parser |String |No a| + +Enter the name of the date/time parser you want to use to interpret your date and time strings. + +You can use a xref:default-date-time-parsers-reference.adoc[default date/time parser] or reference a date/time parser from the <>. + +|==== + +[#numeric_range_filter] +===== Numeric Range Document Filters + +[.status]#Couchbase Server 8.0# + +A numeric range document filter adds or removes documents from a type mapping based on the value of a numeric field and a specified range: + +[source,json] +---- +include::example$simple-search-index-payload.jsonc[tag=numeric_range_filter] +---- + +TIP: To view the entire JSON payload, click btn:[View]. + +Set the name of your numeric range document filter object to the name you want for your filter. +Use this name to use the filter on a <>. +For example, `\{scope\}.\{collection\}.cleanliness_range`. + +A numeric range document filter can have the following properties: + +[cols="2,1,1,4"] +|==== +|Property |Type |Required? |Description + +|min |Number |No a| + +Set the minimum value for the range you want to use as a filter. +Values smaller than your `min` value do not pass the filter. + +You can choose to set only a `min` value or only a `max` value for the filter. + +By default, the value for `min` is included in your numeric range filter. + +|max |Number |No a| + +Set the maximum value for the range you want to use as a filter. +Values larger than your `max` value do not pass the filter. + +You can choose to set only a `min` value or only a `max` value for the filter. + +By default, the value for `max` is excluded from your numeric range filter. + +|inclusive_min |Boolean |No a| + +Set whether the value of `min` should be included or excluded from the range: + +* If `inclusive_min` is `true`, documents with the same value as `min` pass the filter. +* If `inclusive_min` is `false`, documents must have a value that's larger than the value of `min` to pass the filter. + +If you do not set a value for `inclusive_min`, by default, `min` is inclusive to your numeric range. + +|inclusive_max |Boolean |No a| + +Set whether the value of `max` should be included or excluded from the range: + +* If `inclusive_max` is `true`, documents with the same value as `max` pass the filter. +* If `inclusive_max` is `false`, documents must have a value that's smaller than the value of `max` to pass the filter. + +If you do not set a value for `inclusive_max`, by default, `max` is not included in your numeric range. + +|field |String |Yes a| + +Enter the name of the field that contains a numeric value you want to use as a filter. + +|order |Number |Yes a| + +include::partial$order-doc-filter-description.adoc[] + +|==== + +[#term_filter] +===== Term Document Filters + +[.status]#Couchbase Server 8.0# + +A term document filter adds or removes documents from a type mapping based on the existence of a term in a specified document field: + +[source,json] +---- +include::example$simple-search-index-payload.jsonc[tag=term_filter] +---- + +TIP: To view the entire JSON payload, click btn:[View]. + +Set the name of your term document filter object to the name you want for your filter. +Use this name to use the filter on a <>. +For example, `\{scope\}.\{collection\}.name_hotel`. + +A term document filter can have the following properties: + +[cols="2,1,1,4"] +|==== +|Property |Type |Required? |Description + +|term |String |Yes a| + +Enter a string that must exist inside `field` for a document to pass the filter. + +The string must be an exact match for a document to pass. + +|field |String |Yes a| + +Enter the name of the field where you want to search for the value of `term`. + +|order |Number |Yes a| + +include::partial$order-doc-filter-description.adoc[] + +|==== + +[#conjunct_filter] +===== Conjunct Document Filter + +[.status]#Couchbase Server 8.0# + +A conjunct document filter can contain any number of the other document filter types: + +* <> +* <> +* <> +* <> +* <> +* <> + +A document must pass every filter inside the `conjuncts` array to pass a conjunct document filter and be included in a type mapping: + +[source,json] +---- +include::example$simple-search-index-payload.jsonc[tag=conjunct_filter] +---- + +TIP: To view the entire JSON payload, click btn:[View]. + +Set the name of your conjunct document filter object to the name you want for your filter. +Use this name to use the filter on a <>. +For example, `\{scope\}.\{collection\}.free_parking_AND_vacancy`. + +A conjunct document filter can have the following properties: + +[cols="2,1,1,4"] +|==== +|Property |Type |Required? |Description + +|conjuncts |Array of Objects |Yes a| + +Add an object to define each filter you want a document to pass before a document can be included in a type mapping. + +The `conjuncts` array can contain any other document filter type, including additional conjunct and disjunct document filters. +You cannot nest more than 5 conjunct or disjunct document filters inside a single filter. + +|order |Number |Yes a| + +include::partial$order-doc-filter-description.adoc[] + +|==== + +[#disjunct_filter] +===== Disjunct Document Filter + +[.status]#Couchbase Server 8.0# + +A disjunct document filter can contain any number of the other document filter types: + +* <> +* <> +* <> +* <> +* <> +* <> + +A document must pass at least the number of filters you specify as `min` from the `disjuncts` array to pass the filter and be included in a type mapping: + +[source,json] +---- +include::example$simple-search-index-payload.jsonc[tag=disjunct_filter] +---- + +TIP: To view the entire JSON payload, click btn:[View]. + +Set the name of your disjunct document filter object to the name you want for your filter. +Use this name to use the filter on a <>. +For example, `\{scope\}.\{collection\}.location_OR_service`. + +A disjunct document filter can have the following properties: + +[cols="2,1,1,4"] +|==== +|Property |Type |Required? |Description + +|disjuncts |Array of Objects |Yes a| + +Add an object to define each filter you want to run against a document for this disjunct document filter. + +The `disjuncts` array can contain any other document filter type, including additional conjunct and disjunct document filters. +You cannot nest more than 5 conjunct or disjunct document filters inside a single filter. + +|min |Number |Yes a| + +Set `min` to the minimum number of filters from `disjuncts` that a document must pass to be included in a type mapping. + +|order |Number |Yes a| + +include::partial$order-doc-filter-description.adoc[] + |==== [#mapping] diff --git a/modules/search/pages/set-type-identifier.adoc b/modules/search/pages/set-type-identifier.adoc index 7482d544..149071ce 100644 --- a/modules/search/pages/set-type-identifier.adoc +++ b/modules/search/pages/set-type-identifier.adoc @@ -9,6 +9,21 @@ [abstract] {description} +For example, if you added a filter to your type mapping that checked if the value of a field was `true`, only documents with the value `true` for that field would be included in your Search index under that type mapping. +Based on your settings, xref:create-child-field.adoc[child fields] or xref:create-child-mapping.adoc[child mappings] that you define for documents that pass the filter on this type mapping will be returned in search results. + +You can filter based on the value of a field, or part of the value of your document IDs. + +As of Couchbase Server version 8.0, you can filter documents with custom filters based on the value of: + +* xref:search-index-params.adoc#boolean_filter[A boolean field]. +* xref:search-index-params.adoc#date_range_filter[A date field, within a specific range]. +* xref:search-index-params.adoc#numeric_range_filter[A numeric field, within a specific range]. +* xref:search-index-params.adoc#term_filter[A term in a text field]. +* A xref:search-index-params.adoc#conjunct_filter[conjunct] or xref:search-index-params.adoc#disjunct_filter[disjunct] object that combines 2 or more of the available filters. + +You can add up to a maximum of 100 custom document filters on a single Search index. + For more information about type identifiers and type mappings, see xref:customize-index.adoc#type-identifiers[Customize a Search Index with the Web Console]. == Prerequisites @@ -35,11 +50,16 @@ To set a type identifier for a Search index with the Couchbase {page-ui-name}: . Go to *Search*. . Click the index where you want to set a type identifier. -. Click btn:[Edit]. +. Click btn:[Edit]. +. Expand *Type Identifier*. . Do one of the following: .. <> .. <> .. <> +.. (Couchbase Server version 8.0 and later) <> + +WARNING: You cannot use custom document filters with another type of type identifier on your Search index. +If you select an option other than *Custom* after you have defined custom document filters, you'll lose any defined custom filters on your Search index. [#json-type] === Create a JSON Type Field Type Identifier @@ -51,12 +71,12 @@ To only add documents to your Search index that contain a specific field with a + For example, if your documents include a `type` field, you could enter `type` in the *JSON Type Field* field. + -NOTE: You can't use a field as a type identifier if the field name contains a period (.). +NOTE: You cannot use a field as a type identifier if the field name contains a period (.). . Under *Type Mappings*, next to the type mapping where you want to add the type identifier, click btn:[Edit]. . In the *#* field, add a period (.) to the end of the current type mapping name. . After the period, add the exact string from the document field that you want to use as a filter. + -For example, if you wanted your Search index to only return documents that had a `type` value of `hotel`, you could enter `scope.collection.hotel` in the type mapping *#* field. +For example, if you wanted your type mapping to only include documents that had a value of `hotel` in the `type` field, you could enter `scope.collection.hotel` in the type mapping *#* field. . Click btn:[OK]. . Click btn:[Update Index]. @@ -73,7 +93,7 @@ For example, if you know all of your document ID values are prefixed by a string . In the *#* field, add a period (.) to the end of the current type mapping name. . After the period, add the exact prefix from the document's ID value that you want to use as a filter. + -For example, if you wanted your Search index to only return documents that have an prefix of `landmark_`, you could enter `scope.collection.landmark` in the type mapping *#* field. +For example, if you wanted your type mapping to only include documents that have an prefix of `landmark_` in their ID values, you could enter `scope.collection.landmark` in the type mapping *#* field. . Click btn:[OK]. . Click btn:[Update Index]. @@ -90,10 +110,40 @@ For example, if you wanted only documents with ID values that contained `\_40`, . In the *#* field, add a period (.) to the end of the current type mapping name. . After the period, add a match for the regular expression from the document's ID value that you want to use as a filter. + -For example, if you wanted your Search index to only return documents with ID values that contained `_40`, you could enter `scope.collection._40` in the type mapping *#* field. +For example, if you wanted your type mapping to only include documents with ID values that contained `_40`, you could enter `scope.collection._40` in the type mapping *#* field. . Click btn:[OK]. . Click btn:[Update Index]. +[#custom] +=== Create a Custom Document Filter Type Identifier + +[.status]#Couchbase Server 8.0# + +To create a new custom document filter on a Search index with the Couchbase {page-ui-name}: + +. Select *Custom*. +. Click btn:[+ Add Document Filter]. +. In the *Type* field, enter a name for your new document filter. +. In the *Filter* code editor, enter a JSON object to define your document filter. ++ +For more information about the properties for each document filter type, see: ++ +* xref:search-index-params.adoc#boolean_filter[Boolean Document Filters] +* xref:search-index-params.adoc#date_range_filter[Date Range Document Filters] +* xref:search-index-params.adoc#numeric_range_filter[Numeric Range Document Filters] +* xref:search-index-params.adoc#term_filter[Term Document Filters] +* xref:search-index-params.adoc#conjunct_filter[Conjunct Document Filters] +* xref:search-index-params.adoc#disjunct_filter[Disjunct Document Filters] + ++ +. Click btn:[Save]. +. Under *Type Mappings*, next to the type mapping where you want to add the type identifier, click btn:[Edit]. +. In the *#* field, add a period (.) to the end of the current type mapping name. +. After the period, enter the name of the custom document filter that you want to use to filter documents on this type mapping. ++ +For example, if you defined a custom document filter named `free_breakfast_true`, enter `scope.collection.free_breakfast_true` in the type mapping *#* field. +. Click btn:[OK]. +. Click btn:[Update Index]. == Next Steps diff --git a/modules/search/partials/nav.adoc b/modules/search/partials/nav.adoc index ced990c5..a4a3b33e 100644 --- a/modules/search/partials/nav.adoc +++ b/modules/search/partials/nav.adoc @@ -37,10 +37,12 @@ *** xref:8.0@server:search:set-advanced-settings.adoc[] *** xref:8.0@server:search:default-analyzers-reference.adoc[] *** xref:8.0@server:search:default-character-filters-reference.adoc[] + *** xref:8.0@server:search:default-date-time-parsers-reference.adoc[] *** xref:8.0@server:search:default-token-filters-reference.adoc[] *** xref:8.0@server:search:default-tokenizers-reference.adoc[] *** xref:8.0@server:search:default-wordlists-reference.adoc[] *** xref:8.0@server:search:field-data-types-reference.adoc[] + *** xref:8.0@server:search:date-time-parser-layout-styles.adoc[] ** xref:8.0@server:fts:fts-high-availability-for-search.adoc[High Availability for Search] ** xref:8.0@server:fts:fts-architecture.adoc[Search Service Architecture] *** xref:8.0@server:fts:fts-architecture-scatter-gather.adoc[Scatter Gather] diff --git a/modules/search/partials/order-doc-filter-description.adoc b/modules/search/partials/order-doc-filter-description.adoc new file mode 100644 index 00000000..3eb9cd3e --- /dev/null +++ b/modules/search/partials/order-doc-filter-description.adoc @@ -0,0 +1,11 @@ +Set the filtering order for this document filter, compared to the other document filters in use on the Search index. + +The Search Service applies document filters on type mappings in the order you specify. +For example, if a document does not pass a type mapping filter where `"order": 1`, the Search Service checks the document against the filter with `"order": 2`. + +The Search Service continues checking documents against any filters defined on type mappings in your Search index until a document passes a filter, or there are no more defined type mapping filters. + +If a document does not pass any defined filters, it's not included in your Search index. + +TIP: If you're defining a document filter inside a `conjuncts` or `disjuncts` array, you do not need to include the `order` property for each filter object. +Add the `order` property to the `conjuncts` or `disjuncts` filter object, instead. \ No newline at end of file diff --git a/preview/HEAD.yml b/preview/HEAD.yml index 51037944..770ab018 100644 --- a/preview/HEAD.yml +++ b/preview/HEAD.yml @@ -1,5 +1,5 @@ sources: docs-server: - branches: [release/7.6] + branches: [release/8.0] override: startPage: server:introduction:intro.adoc