From a331b8ad8c70f3709f8786ee7865aeaa9b885a27 Mon Sep 17 00:00:00 2001 From: Ray Offiah Date: Mon, 24 Feb 2025 15:19:18 +0000 Subject: [PATCH 1/2] [DOC-12282]: Feedback on Search Functions. Add a link to the page explaining how to add a search index through the UI console. Integrated a reusable prerequisites section for setting up demonstration search indexes, ensuring consistent instructions across related documentation. Updated existing N1QL Search Function content to reference the new section and adjusted formatting for clarity. --- .../n1ql-language-reference/searchfun.adoc | 15 +- ...onstration-index-prerequisite-section.adoc | 199 ++++++++++++++++++ 2 files changed, 205 insertions(+), 9 deletions(-) create mode 100644 modules/n1ql/partials/demonstration-index-prerequisite-section.adoc diff --git a/modules/n1ql/pages/n1ql-language-reference/searchfun.adoc b/modules/n1ql/pages/n1ql-language-reference/searchfun.adoc index 7185a79a4..2ce60878a 100644 --- a/modules/n1ql/pages/n1ql-language-reference/searchfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/searchfun.adoc @@ -8,27 +8,24 @@ Search functions enable you to use xref:search:search.adoc[Full Text Search (FTS)] queries directly within a {sqlpp} query. -[float] -=== Prerequisites +[#prerequisities, float] +== Prerequisites To use any of the search functions, the Search Service must be available on the cluster. It's recommended that you create a suitable Search index for the searches that you want to run. For more information, refer to xref:search:create-search-indexes.adoc[]. -[NOTE] --- -The examples in this page all assume that demonstration Search indexes have been created, as described in xref:fts:fts-demonstration-indexes.adoc[Demonstration Indexes]. --- +include::partial$demonstration-index-prerequisite-section.adoc[] [float] -=== Authorization +== Authorization You do not need credentials for the Search Service to be able to use the search functions in a query. The role *Data Admin* must be assigned to those who intend to create indexes; and the role *Data Reader* to those who intend to perform searches. For information on creating users and assigning roles, see xref:learn:security/authorization-overview.adoc[Authorization]. [float] -=== When to Use Search Functions +== When to Use Search Functions The search functions are useful when you need to combine a Full Text Search with the power of a {sqlpp} query; for example, combining joins and natural-language search in the same query. @@ -381,7 +378,7 @@ WHERE t1.type = "hotel" AND SEARCH(t1.description, "amazing"); ---- If the Full Text Search index being queried has its default mapping disabled and has a custom type mapping defined, the query needs to specify the type explicitly. -The above query uses the demonstration index xref:fts:fts-demonstration-indexes.adoc#travel-sample-index-hotel-description[travel-sample-index-hotel-description], which has the custom type mapping "hotel". +The above query uses the xref:prerequisities[demonstration index], which has the custom type mapping "hotel". For more information about defining custom type mappings within a Search index, refer to xref:search:create-type-mapping.adoc[Create a Type Mapping]. Note that for {sqlpp} queries, only Search indexes with one type mapping are searchable. diff --git a/modules/n1ql/partials/demonstration-index-prerequisite-section.adoc b/modules/n1ql/partials/demonstration-index-prerequisite-section.adoc new file mode 100644 index 000000000..566359d02 --- /dev/null +++ b/modules/n1ql/partials/demonstration-index-prerequisite-section.adoc @@ -0,0 +1,199 @@ +To run the examples on this page, you will need to create three indexes. + +To create the indexes, you can use: + +* The index editor built into the web console. +* The REST API +* The command line utility. + +For this exercise, the easiest way is to use the web console to import the index definitions below. + +If you need more information on creating search indexes using Couchbase Web UI, see xref:search:create-search-index-ui.adoc[] + + +[tabs] +==== +travel-sample-index-unstored:: ++ +-- +[source,json] +---- + +{ + "name": "travel-sample-index-unstored", + "type": "fulltext-index", + "params": { + "doc_config": { + "docid_prefix_delim": "", + "docid_regexp": "", + "mode": "type_field", + "type_field": "type" + }, + "mapping": { + "analysis": { + "analyzers": { + "singleAnalyzer": { + "tokenizer": "single", + "type": "custom" + } + } + }, + "default_analyzer": "standard", + "default_datetime_parser": "dateTimeOptional", + "default_field": "_all", + "default_mapping": { + "dynamic": true, + "enabled": true + }, + "default_type": "_default", + "docvalues_dynamic": false, + "index_dynamic": true, + "store_dynamic": false, + "type_field": "_type" + }, + "store": { + "indexType": "scorch", + "segmentVersion": 15 + } + }, + "sourceType": "gocbcore", + "sourceName": "travel-sample", + "sourceUUID": "94387e8a4cefe4abeb51d92e28a696c6", + "sourceParams": {}, + "planParams": { + "maxPartitionsPerPIndex": 1024, + "indexPartitions": 1, + "numReplicas": 0 + }, + "uuid": "5e26bbd6c2c87069" +} +---- +-- + +travel-sample-index-stored:: ++ +-- +[source,json] +---- +{ + "name": "travel-sample-index-stored", + "type": "fulltext-index", + "params": { + "doc_config": { + "docid_prefix_delim": "", + "docid_regexp": "", + "mode": "type_field", + "type_field": "type" + }, + "mapping": { + "analysis": { + "analyzers": { + "letterAnalyzer": { + "tokenizer": "letter", + "type": "custom" + } + } + }, + "default_analyzer": "standard", + "default_datetime_parser": "dateTimeOptional", + "default_field": "_all", + "default_mapping": { + "dynamic": true, + "enabled": true + }, + "default_type": "_default", + "docvalues_dynamic": false, + "index_dynamic": true, + "store_dynamic": true, + "type_field": "_type" + }, + "store": { + "indexType": "scorch", + "segmentVersion": 15 + } + }, + "sourceType": "gocbcore", + "sourceName": "travel-sample", + "sourceUUID": "94387e8a4cefe4abeb51d92e28a696c6", + "sourceParams": {}, + "planParams": { + "maxPartitionsPerPIndex": 1024, + "indexPartitions": 1, + "numReplicas": 0 + }, + "uuid": "16d6602d3193b526" +} +---- + +-- + +geoIndex:: ++ +-- + +[source,json] +---- + +{ + "name": "geoIndex", + "type": "fulltext-index", + "params": { + "doc_config": { + "docid_prefix_delim": "", + "docid_regexp": "", + "mode": "type_field", + "type_field": "type" + }, + "mapping": { + "default_analyzer": "standard", + "default_datetime_parser": "dateTimeOptional", + "default_field": "_all", + "default_mapping": { + "dynamic": true, + "enabled": true, + "properties": { + "geo": { + "enabled": true, + "dynamic": false, + "fields": [ + { + "include_in_all": true, + "index": true, + "name": "geo", + "store": true, + "type": "geopoint" + } + ] + } + } + }, + "default_type": "_default", + "docvalues_dynamic": false, + "index_dynamic": true, + "store_dynamic": false, + "type_field": "_type" + }, + "store": { + "indexType": "scorch", + "segmentVersion": 15, + "spatialPlugin": "s2" + } + }, + "sourceType": "gocbcore", + "sourceName": "travel-sample", + "sourceUUID": "94387e8a4cefe4abeb51d92e28a696c6", + "sourceParams": {}, + "planParams": { + "maxPartitionsPerPIndex": 1024, + "indexPartitions": 1, + "numReplicas": 0 + }, + "uuid": "445bceb9301d0d74" +} +---- + + +-- + + +==== From fb1253fe101e97514871383876890317f16466d4 Mon Sep 17 00:00:00 2001 From: Ray Offiah Date: Tue, 25 Feb 2025 09:23:17 +0000 Subject: [PATCH 2/2] [DOC-12282]: Feedback on Search Functions. Replaced a reusable partial with full inline index definitions in N1QL documentation. --- .../n1ql-language-reference/searchfun.adoc | 201 +++++++++++++++++- ...onstration-index-prerequisite-section.adoc | 199 ----------------- 2 files changed, 200 insertions(+), 200 deletions(-) delete mode 100644 modules/n1ql/partials/demonstration-index-prerequisite-section.adoc diff --git a/modules/n1ql/pages/n1ql-language-reference/searchfun.adoc b/modules/n1ql/pages/n1ql-language-reference/searchfun.adoc index 2ce60878a..1b14ac314 100644 --- a/modules/n1ql/pages/n1ql-language-reference/searchfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/searchfun.adoc @@ -15,7 +15,206 @@ To use any of the search functions, the Search Service must be available on the It's recommended that you create a suitable Search index for the searches that you want to run. For more information, refer to xref:search:create-search-indexes.adoc[]. -include::partial$demonstration-index-prerequisite-section.adoc[] +To run the examples on this page, you will need to create three indexes. + +To create the indexes, you can use: + +* The index editor built into the web console. +* The REST API +* The command line utility. + +For this exercise, the easiest way is to use the web console to import the index definitions below. + +If you need more information on creating search indexes using Couchbase Web UI, see xref:search:create-search-index-ui.adoc[] + + +[tabs] +==== +travel-sample-index-unstored:: ++ +-- +[source,json] +---- + +{ + "name": "travel-sample-index-unstored", + "type": "fulltext-index", + "params": { + "doc_config": { + "docid_prefix_delim": "", + "docid_regexp": "", + "mode": "type_field", + "type_field": "type" + }, + "mapping": { + "analysis": { + "analyzers": { + "singleAnalyzer": { + "tokenizer": "single", + "type": "custom" + } + } + }, + "default_analyzer": "standard", + "default_datetime_parser": "dateTimeOptional", + "default_field": "_all", + "default_mapping": { + "dynamic": true, + "enabled": true + }, + "default_type": "_default", + "docvalues_dynamic": false, + "index_dynamic": true, + "store_dynamic": false, + "type_field": "_type" + }, + "store": { + "indexType": "scorch", + "segmentVersion": 15 + } + }, + "sourceType": "gocbcore", + "sourceName": "travel-sample", + "sourceUUID": "94387e8a4cefe4abeb51d92e28a696c6", + "sourceParams": {}, + "planParams": { + "maxPartitionsPerPIndex": 1024, + "indexPartitions": 1, + "numReplicas": 0 + }, + "uuid": "5e26bbd6c2c87069" +} +---- +-- + +travel-sample-index-stored:: ++ +-- +[source,json] +---- +{ + "name": "travel-sample-index-stored", + "type": "fulltext-index", + "params": { + "doc_config": { + "docid_prefix_delim": "", + "docid_regexp": "", + "mode": "type_field", + "type_field": "type" + }, + "mapping": { + "analysis": { + "analyzers": { + "letterAnalyzer": { + "tokenizer": "letter", + "type": "custom" + } + } + }, + "default_analyzer": "standard", + "default_datetime_parser": "dateTimeOptional", + "default_field": "_all", + "default_mapping": { + "dynamic": true, + "enabled": true + }, + "default_type": "_default", + "docvalues_dynamic": false, + "index_dynamic": true, + "store_dynamic": true, + "type_field": "_type" + }, + "store": { + "indexType": "scorch", + "segmentVersion": 15 + } + }, + "sourceType": "gocbcore", + "sourceName": "travel-sample", + "sourceUUID": "94387e8a4cefe4abeb51d92e28a696c6", + "sourceParams": {}, + "planParams": { + "maxPartitionsPerPIndex": 1024, + "indexPartitions": 1, + "numReplicas": 0 + }, + "uuid": "16d6602d3193b526" +} +---- + +-- + +geoIndex:: ++ +-- + +[source,json] +---- + +{ + "name": "geoIndex", + "type": "fulltext-index", + "params": { + "doc_config": { + "docid_prefix_delim": "", + "docid_regexp": "", + "mode": "type_field", + "type_field": "type" + }, + "mapping": { + "default_analyzer": "standard", + "default_datetime_parser": "dateTimeOptional", + "default_field": "_all", + "default_mapping": { + "dynamic": true, + "enabled": true, + "properties": { + "geo": { + "enabled": true, + "dynamic": false, + "fields": [ + { + "include_in_all": true, + "index": true, + "name": "geo", + "store": true, + "type": "geopoint" + } + ] + } + } + }, + "default_type": "_default", + "docvalues_dynamic": false, + "index_dynamic": true, + "store_dynamic": false, + "type_field": "_type" + }, + "store": { + "indexType": "scorch", + "segmentVersion": 15, + "spatialPlugin": "s2" + } + }, + "sourceType": "gocbcore", + "sourceName": "travel-sample", + "sourceUUID": "94387e8a4cefe4abeb51d92e28a696c6", + "sourceParams": {}, + "planParams": { + "maxPartitionsPerPIndex": 1024, + "indexPartitions": 1, + "numReplicas": 0 + }, + "uuid": "445bceb9301d0d74" +} +---- + + +-- + + +==== + [float] == Authorization diff --git a/modules/n1ql/partials/demonstration-index-prerequisite-section.adoc b/modules/n1ql/partials/demonstration-index-prerequisite-section.adoc deleted file mode 100644 index 566359d02..000000000 --- a/modules/n1ql/partials/demonstration-index-prerequisite-section.adoc +++ /dev/null @@ -1,199 +0,0 @@ -To run the examples on this page, you will need to create three indexes. - -To create the indexes, you can use: - -* The index editor built into the web console. -* The REST API -* The command line utility. - -For this exercise, the easiest way is to use the web console to import the index definitions below. - -If you need more information on creating search indexes using Couchbase Web UI, see xref:search:create-search-index-ui.adoc[] - - -[tabs] -==== -travel-sample-index-unstored:: -+ --- -[source,json] ----- - -{ - "name": "travel-sample-index-unstored", - "type": "fulltext-index", - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "", - "mode": "type_field", - "type_field": "type" - }, - "mapping": { - "analysis": { - "analyzers": { - "singleAnalyzer": { - "tokenizer": "single", - "type": "custom" - } - } - }, - "default_analyzer": "standard", - "default_datetime_parser": "dateTimeOptional", - "default_field": "_all", - "default_mapping": { - "dynamic": true, - "enabled": true - }, - "default_type": "_default", - "docvalues_dynamic": false, - "index_dynamic": true, - "store_dynamic": false, - "type_field": "_type" - }, - "store": { - "indexType": "scorch", - "segmentVersion": 15 - } - }, - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "sourceUUID": "94387e8a4cefe4abeb51d92e28a696c6", - "sourceParams": {}, - "planParams": { - "maxPartitionsPerPIndex": 1024, - "indexPartitions": 1, - "numReplicas": 0 - }, - "uuid": "5e26bbd6c2c87069" -} ----- --- - -travel-sample-index-stored:: -+ --- -[source,json] ----- -{ - "name": "travel-sample-index-stored", - "type": "fulltext-index", - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "", - "mode": "type_field", - "type_field": "type" - }, - "mapping": { - "analysis": { - "analyzers": { - "letterAnalyzer": { - "tokenizer": "letter", - "type": "custom" - } - } - }, - "default_analyzer": "standard", - "default_datetime_parser": "dateTimeOptional", - "default_field": "_all", - "default_mapping": { - "dynamic": true, - "enabled": true - }, - "default_type": "_default", - "docvalues_dynamic": false, - "index_dynamic": true, - "store_dynamic": true, - "type_field": "_type" - }, - "store": { - "indexType": "scorch", - "segmentVersion": 15 - } - }, - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "sourceUUID": "94387e8a4cefe4abeb51d92e28a696c6", - "sourceParams": {}, - "planParams": { - "maxPartitionsPerPIndex": 1024, - "indexPartitions": 1, - "numReplicas": 0 - }, - "uuid": "16d6602d3193b526" -} ----- - --- - -geoIndex:: -+ --- - -[source,json] ----- - -{ - "name": "geoIndex", - "type": "fulltext-index", - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "", - "mode": "type_field", - "type_field": "type" - }, - "mapping": { - "default_analyzer": "standard", - "default_datetime_parser": "dateTimeOptional", - "default_field": "_all", - "default_mapping": { - "dynamic": true, - "enabled": true, - "properties": { - "geo": { - "enabled": true, - "dynamic": false, - "fields": [ - { - "include_in_all": true, - "index": true, - "name": "geo", - "store": true, - "type": "geopoint" - } - ] - } - } - }, - "default_type": "_default", - "docvalues_dynamic": false, - "index_dynamic": true, - "store_dynamic": false, - "type_field": "_type" - }, - "store": { - "indexType": "scorch", - "segmentVersion": 15, - "spatialPlugin": "s2" - } - }, - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "sourceUUID": "94387e8a4cefe4abeb51d92e28a696c6", - "sourceParams": {}, - "planParams": { - "maxPartitionsPerPIndex": 1024, - "indexPartitions": 1, - "numReplicas": 0 - }, - "uuid": "445bceb9301d0d74" -} ----- - - --- - - -====