Skip to content

Commit 47646ac

Browse files
sarahlweltonosfameron
sarahlwelton
authored and
osfameron
committed
[DOC-12754] First draft of additional filters documentation
[DOC-12754] Correct search-request-params.adoc [DOC-12754] Update HEAD.yml for previews [DOC-12754] Add version/status labels and tweak language [DOC-12754] Add additional version status labels for clarity [NO ISSUE] Straightening out lots of merge conflicts and inconsistencies in search-request-params [DOC-12752] Fix search-request-params pls
1 parent a38b065 commit 47646ac

11 files changed

+748
-17
lines changed

‎modules/search/examples/create-search-index-payload-filters.sh

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
curl -s -XPUT -H "Content-Type: application/json" \
2+
-u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/bucket/travel-sample/scope/inventory/index/travel-sample-filter-index
3+
-d \
4+
'{
5+
"type": "fulltext-index",
6+
"name": "travel-sample.inventory.travel-sample-filter",
7+
"sourceType": "gocbcore",
8+
"sourceName": "travel-sample",
9+
"planParams": {
10+
"maxPartitionsPerPIndex": 128,
11+
"indexPartitions": 1
12+
},
13+
"params": {
14+
"doc_config": {
15+
"doc_filter": {
16+
"cleanliness_AND_free_breakfast": {
17+
"conjuncts": [
18+
{
19+
"field": "reviews.ratings.Cleanliness",
20+
"inclusive_max": true,
21+
"max": 5,
22+
"min": 3
23+
},
24+
{
25+
"bool": true,
26+
"field": "free_breakfast"
27+
}
28+
],
29+
"order": 1
30+
}
31+
},
32+
"docid_prefix_delim": "",
33+
"docid_regexp": "",
34+
"mode": "scope.collection.custom",
35+
"type_field": "type"
36+
},
37+
"mapping": {
38+
"analysis": {},
39+
"default_analyzer": "standard",
40+
"default_datetime_parser": "dateTimeOptional",
41+
"default_field": "_all",
42+
"default_mapping": {
43+
"dynamic": true,
44+
"enabled": false
45+
},
46+
"default_type": "_default",
47+
"docvalues_dynamic": false,
48+
"index_dynamic": true,
49+
"store_dynamic": false,
50+
"type_field": "_type",
51+
"types": {
52+
"inventory.hotel.cleanliness_AND_free_breakfast": {
53+
"dynamic": false,
54+
"enabled": true,
55+
"properties": {
56+
"description": {
57+
"dynamic": false,
58+
"enabled": true,
59+
"fields": [
60+
{
61+
"docvalues": true,
62+
"include_in_all": true,
63+
"include_term_vectors": true,
64+
"index": true,
65+
"name": "description",
66+
"store": true,
67+
"type": "text"
68+
}
69+
]
70+
},
71+
"free_breakfast": {
72+
"dynamic": false,
73+
"enabled": true,
74+
"fields": [
75+
{
76+
"docvalues": true,
77+
"include_in_all": true,
78+
"index": true,
79+
"name": "free_breakfast",
80+
"store": true,
81+
"type": "boolean"
82+
}
83+
]
84+
},
85+
"name": {
86+
"dynamic": false,
87+
"enabled": true,
88+
"fields": [
89+
{
90+
"docvalues": true,
91+
"include_in_all": true,
92+
"include_term_vectors": true,
93+
"index": true,
94+
"name": "name",
95+
"store": true,
96+
"type": "text"
97+
}
98+
]
99+
},
100+
"reviews": {
101+
"dynamic": false,
102+
"enabled": true,
103+
"properties": {
104+
"content": {
105+
"dynamic": false,
106+
"enabled": true,
107+
"fields": [
108+
{
109+
"docvalues": true,
110+
"include_in_all": true,
111+
"include_term_vectors": true,
112+
"index": true,
113+
"name": "content",
114+
"store": true,
115+
"type": "text"
116+
}
117+
]
118+
},
119+
"ratings": {
120+
"dynamic": false,
121+
"enabled": true,
122+
"properties": {
123+
"Cleanliness": {
124+
"dynamic": false,
125+
"enabled": true,
126+
"fields": [
127+
{
128+
"docvalues": true,
129+
"include_in_all": true,
130+
"index": true,
131+
"name": "Cleanliness",
132+
"store": true,
133+
"type": "number"
134+
}
135+
]
136+
}
137+
}
138+
}
139+
}
140+
}
141+
}
142+
}
143+
}
144+
},
145+
"store": {
146+
"indexType": "scorch",
147+
"segmentVersion": 16
148+
}
149+
},
150+
"sourceParams": {}
151+
}'

‎modules/search/examples/create-search-index-response-filters.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"status": "ok",
3+
"name": "travel-sample.inventory.travel-sample-filter-index",
4+
"uuid": "5454607bd6b4b3e1"
5+
}

‎modules/search/examples/simple-search-index-payload.jsonc

Lines changed: 92 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,78 @@
2020
"doc_config": {
2121
"docid_prefix_delim": "",
2222
"docid_regexp": "",
23-
"mode": "scope.collection.type_field",
24-
"type_field": "type"
23+
"mode": "scope.collection.custom",
24+
"type_field": "type",
25+
// tag::doc_filter[]
26+
"doc_filter": {
27+
// tag::boolean_filter[]
28+
"free_breakfast_true": {
29+
"bool": true,
30+
"field": "free_breakfast",
31+
"order": 1
32+
},
33+
// end::boolean_filter[]
34+
// tag::date_range_filter[]
35+
"review_date_range": {
36+
"start": "2015-01-01",
37+
"end": "2019-01-01",
38+
"inclusive_end": true,
39+
"inclusive_start": false,
40+
"field": "reviews.date",
41+
"order": 2,
42+
"datetime_parser": "My_Date_Time_Parser"
43+
},
44+
// end::date_range_filter[]
45+
// tag::numeric_range_filter[]
46+
"cleanliness_range": {
47+
"min": 3,
48+
"max": 5,
49+
"inclusive_min": true,
50+
"inclusive_max": true,
51+
"field": "reviews.ratings.Cleanliness",
52+
"order": 3
53+
},
54+
// end::numeric_range_filter[]
55+
// tag::conjunct_filter[]
56+
"free_parking_AND_vacancy": {
57+
"conjuncts": [
58+
{
59+
"bool": true,
60+
"field": "vacancy"
61+
},
62+
{
63+
"bool": true,
64+
"field": "free_parking"
65+
}
66+
],
67+
"order": 4
68+
},
69+
// end::conjunct_filter[]
70+
// tag::disjunct_filter[]
71+
"location_OR_service": {
72+
"disjuncts": [
73+
{
74+
"min": 5,
75+
"field": "reviews.ratings.Service"
76+
},
77+
{
78+
"min": 5,
79+
"field": "reviews.ratings.Location"
80+
}
81+
],
82+
"order": 6
83+
},
84+
// end::disjunct_filter[]
85+
// tag::term_filter[]
86+
"name_hotel": {
87+
"term": "Hotel",
88+
"order": 5,
89+
"field": "name"
90+
}
91+
// end::term_filter[]
92+
93+
}
94+
// end::doc_filter[]
2595
},
2696
// end::doc_config[]
2797
// tag::mapping[]
@@ -194,6 +264,26 @@
194264
]
195265
}
196266
}
267+
},
268+
"inventory.hotel.free_breakfast_true": {
269+
"dynamic": true,
270+
"enabled": true,
271+
"properties": {
272+
"free_breakfast": {
273+
"dynamic": false,
274+
"enabled": true,
275+
"fields": [
276+
{
277+
"docvalues": true,
278+
"include_in_all": true,
279+
"index": true,
280+
"name": "free_breakfast",
281+
"store": true,
282+
"type": "boolean"
283+
}
284+
]
285+
}
286+
}
197287
}
198288
// end::scope_collection[]
199289
}

‎modules/search/pages/create-search-index-rest-api.adoc

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ Do not include the xref:search-index-params.adoc#uuid[uuid] or xref:search-index
5555
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.
5656
For more information about how to create an index with the UI, see xref:create-search-index-ui.adoc[].
5757

58-
=== Example
58+
=== Example: Simple Search Index with XATTRs
5959

6060
In the following example, the JSON payload creates a simple index named `landmark-content-index` on the `travel-sample` bucket.
6161
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[]
7979
The `"uuid"` is randomly generated for each Search index you create.
8080
Your own UUID might not match the value shown in the example.
8181

82+
=== Example: Search Index with Custom Document Filter
83+
84+
[.status]#Couchbase Server 8.0#
85+
86+
In the following example, the JSON payload creates a Search index named `travel-sample-filter` on the `travel-sample` bucket.
87+
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.
88+
Only documents with a cleanliness rating between 3 and 5 and `free_breakfast` set to `true` are included from the `inventory.hotel` collection.
89+
90+
For documents that pass the filter, the index includes the `description`, `free_breakfast`, `name`, `reviews.content`, and `reviews.ratings.Cleanliness` fields:
91+
92+
[source,console]
93+
----
94+
include::example$create-search-index-payload-filters.sh[]
95+
----
96+
97+
For more information about the available JSON properties for a Search index, see xref:search-index-params.adoc[].
98+
99+
If the REST API call is successful, the Search Service returns a `200 OK` and the following JSON response:
100+
101+
[source,json]
102+
----
103+
include::example$create-search-index-response-filters.json[]
104+
----
105+
106+
The `"uuid"` is randomly generated for each Search index you create.
107+
Your own UUID might not match the value shown in the example.
108+
82109
== Next Steps
83110

84111
After you create a Search index, you can xref:simple-search-rest-api.adoc[] to test your Search index.

‎modules/search/pages/create-type-mapping.adoc

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,10 @@ To create a type mapping with the Couchbase {page-ui-name}:
3131
. Do one of the following:
3232
.. If you selected *Use non-default scope/collection(s)*, in the *Collection* list, select the collection where you want to create the type mapping.
3333
.. 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.
34-
. (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.
34+
. (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.
35+
+
36+
For example, `inventory.hotel.free_breakfast_true` or `inventory.hotel.hotel`.
3537
+
36-
For example, `scope.collection.document_type`.
3738
For more information, see xref:set-type-identifier.adoc[].
3839
. (Optional) To use a specific analyzer for documents in the type mapping, in the *Analyzer* list, select an analyzer.
3940
+

‎modules/search/pages/customize-index.adoc

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,15 @@ You can add the following components and configure the following options for a S
1919
|[[type-identifiers]]Type Identifier
2020
|
2121
|✓
22-
a|Set a type identifier to add a filter to the documents added to your Search index:
22+
a|Set a type identifier to add a filter to the documents added to your Search index through a <<type-mapping,type mapping>>:
2323

2424
* JSON Type Field: Selects only documents that contain a specific field with a specified string value.
2525
* Doc ID up to Separator: Selects only documents with an ID or key up to a specific substring.
2626
* Doc ID with Regex: Selects only documents with an ID or key that matches a regular expression.
27+
* [.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.
28+
29+
Type identifiers add a more granular filter to the documents in a type mapping.
30+
If a type mapping has a type identifier, only documents that match the type identifier can be included in the Search index.
2731

2832
For more information about how to configure a type identifier, see xref:set-type-identifier.adoc[].
2933

@@ -32,7 +36,7 @@ For more information about how to configure a type identifier, see xref:set-type
3236
|&check;
3337
a|Use a type mapping to include or exclude specific documents in a collection from an index.
3438

35-
Type mappings can also set a field's data type and other settings.
39+
Type mappings can also set a document field's data type and other settings.
3640

3741
You can create two types of type mappings with the Search Service:
3842

@@ -52,6 +56,9 @@ Type mappings start at the collection level.
5256
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.
5357
This can improve Search index performance over indexing entire collections.
5458

59+
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.
60+
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.
61+
5562
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].
5663

5764
For more information about how to configure settings for mappings and type mappings in the Quick Editor, see xref:quick-index-field-options.adoc[].

0 commit comments

Comments
 (0)