From f9f23326ee981ea8215f75ed4351533bedb38aab Mon Sep 17 00:00:00 2001 From: Sarah Welton Date: Tue, 19 Mar 2024 14:59:44 -0400 Subject: [PATCH] [DOC-11985] Cleaning up old fts/ files that have been replaced by new documentation. Changing nav.adoc to move search partial and remove all fts content (it's moving to docs-devex nav partial) --- modules/ROOT/nav.adoc | 109 +- .../pages/fts-configure-index-options.adoc | 17 - .../pages/fts-creating-full-text-aliases.adoc | 27 - .../fts-creating-index-from-REST-dynamic.adoc | 219 -- .../fts-creating-index-from-REST-geojson.adoc | 339 --- ...fts-creating-index-from-REST-geopoint.adoc | 263 -- .../fts-creating-index-from-REST-legacy.adoc | 214 -- ...fts-creating-index-from-REST-onefield.adoc | 374 --- ...-index-from-UI-classic-editor-dynamic.adoc | 103 - ...index-from-UI-classic-editor-geopoint.adoc | 81 - ...g-index-from-UI-classic-editor-legacy.adoc | 72 - ...index-from-UI-classic-editor-onefield.adoc | 126 - ...creating-index-from-UI-classic-editor.adoc | 11 - ...fference-between-classic-quick-editor.adoc | 40 - ...s-creating-index-from-UI-quick-editor.adoc | 115 - .../fts-creating-index-with-rest-api.adoc | 106 - modules/fts/pages/fts-creating-indexes.adoc | 35 - ...ith-curl-http-requests-json-structure.adoc | 80 - .../fts-creating-with-curl-http-requests.adoc | 2180 ----------------- modules/fts/pages/fts-custom-filters.adoc | 145 -- modules/fts/pages/fts-date-time-parsers.adoc | 48 - modules/fts/pages/fts-default-settings.adoc | 46 - modules/fts/pages/fts-index-analyzers.adoc | 481 ---- modules/fts/pages/fts-index-partitions.adoc | 34 - modules/fts/pages/fts-index-replicas.adoc | 18 - modules/fts/pages/fts-index-type.adoc | 37 - modules/fts/pages/fts-introduction.adoc | 135 - .../fts/pages/fts-manage-index-lifecycle.adoc | 26 - .../pages/fts-multi-collection-behaviour.adoc | 220 -- modules/fts/pages/fts-perform-searches.adoc | 22 - .../fts-query-string-syntax-boosting.adoc | 32 - .../fts-query-string-syntax-date-ranges.adoc | 6 - .../fts-query-string-syntax-escaping.adoc | 18 - ...fts-query-string-syntax-field-scoping.adoc | 25 - .../fts-query-string-syntax-match-phrase.adoc | 10 - .../pages/fts-query-string-syntax-match.adoc | 24 - ...ts-query-string-syntax-numeric-ranges.adoc | 8 - .../fts/pages/fts-query-string-syntax.adoc | 15 - modules/fts/pages/fts-queryshape-circle.adoc | 468 ---- .../fts/pages/fts-queryshape-envelope.adoc | 446 ---- .../fts-queryshape-geometrycollection.adoc | 612 ----- .../fts/pages/fts-queryshape-linestring.adoc | 361 --- .../pages/fts-queryshape-multilinestring.adoc | 331 --- .../fts/pages/fts-queryshape-multipoint.adoc | 396 --- .../pages/fts-queryshape-multipolygon.adoc | 514 ---- modules/fts/pages/fts-queryshape-point.adoc | 297 --- modules/fts/pages/fts-queryshape-polygon.adoc | 523 ---- modules/fts/pages/fts-quickstart-guide.adoc | 48 - modules/fts/pages/fts-search-request.adoc | 983 -------- .../fts/pages/fts-searching-from-N1QL.adoc | 685 ------ .../fts/pages/fts-searching-from-the-UI.adoc | 91 - ...s-searching-full-text-indexes-aliases.adoc | 31 - ...fts-searching-with-curl-http-requests.adoc | 163 -- modules/fts/pages/fts-searching-with-sdk.adoc | 67 - modules/fts/pages/fts-secure-fts-queries.adoc | 26 - .../fts-supported-queries-analytic-query.adoc | 11 - ...supported-queries-boolean-field-query.adoc | 20 - .../fts-supported-queries-compound-query.adoc | 8 - ...supported-queries-conjuncts-disjuncts.adoc | 40 - .../fts-supported-queries-date-range.adoc | 23 - .../pages/fts-supported-queries-fuzzy.adoc | 24 - ...supported-queries-geo-bounded-polygon.adoc | 71 - ...pported-queries-geo-bounded-rectangle.adoc | 73 - ...-supported-queries-geo-point-distance.adoc | 82 - ...fts-supported-queries-geojson-spatial.adoc | 1059 -------- ...ts-supported-queries-geopoint-spatial.adoc | 585 ----- .../fts-supported-queries-geospatial.adoc | 16 - .../fts-supported-queries-match-all.adoc | 9 - .../fts-supported-queries-match-none.adoc | 8 - .../fts-supported-queries-match-phrase.adoc | 23 - .../pages/fts-supported-queries-match.adoc | 40 - ...-supported-queries-non-analytic-query.adoc | 15 - .../fts-supported-queries-numeric-range.adoc | 38 - .../pages/fts-supported-queries-phrase.adoc | 17 - .../fts-supported-queries-prefix-query.adoc | 12 - ...-supported-queries-query-string-query.adoc | 18 - .../fts-supported-queries-range-query.adoc | 9 - .../pages/fts-supported-queries-regexp.adoc | 14 - .../fts-supported-queries-special-query.adoc | 8 - .../fts-supported-queries-term-range.adoc | 17 - .../fts/pages/fts-supported-queries-term.adoc | 15 - .../pages/fts-supported-queries-wildcard.adoc | 16 - modules/fts/pages/fts-supported-queries.adoc | 31 - modules/fts/pages/fts-type-identifiers.adoc | 28 - .../fts-type-mapping-specifying-fields.adoc | 27 - .../fts-type-mappings-Docid-with-regexp.adoc | 66 - ...ype-mappings-add-child-field-analyzer.adoc | 9 - ...pe-mappings-add-child-field-docvalues.adoc | 13 - ...e-mappings-add-child-field-field-name.adoc | 8 - ...s-add-child-field-field-searchable-as.adoc | 8 - ...e-mappings-add-child-field-field-type.adoc | 11 - ...-add-child-field-include-in-all-field.adoc | 16 - ...-add-child-field-include-term-vectors.adoc | 14 - ...s-type-mappings-add-child-field-index.adoc | 10 - ...s-type-mappings-add-child-field-store.adoc | 22 - .../fts-type-mappings-add-child-field.adoc | 42 - .../fts-type-mappings-add-child-mappings.adoc | 29 - modules/fts/pages/fts-type-mappings.adoc | 465 ---- 98 files changed, 2 insertions(+), 14971 deletions(-) delete mode 100644 modules/fts/pages/fts-configure-index-options.adoc delete mode 100644 modules/fts/pages/fts-creating-full-text-aliases.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-REST-dynamic.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-REST-geojson.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-REST-geopoint.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-REST-legacy.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-REST-onefield.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-UI-classic-editor-dynamic.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-UI-classic-editor-geopoint.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-UI-classic-editor-legacy.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-UI-classic-editor-onefield.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-UI-classic-editor.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-UI-difference-between-classic-quick-editor.adoc delete mode 100644 modules/fts/pages/fts-creating-index-from-UI-quick-editor.adoc delete mode 100644 modules/fts/pages/fts-creating-index-with-rest-api.adoc delete mode 100644 modules/fts/pages/fts-creating-indexes.adoc delete mode 100644 modules/fts/pages/fts-creating-with-curl-http-requests-json-structure.adoc delete mode 100644 modules/fts/pages/fts-creating-with-curl-http-requests.adoc delete mode 100644 modules/fts/pages/fts-custom-filters.adoc delete mode 100644 modules/fts/pages/fts-date-time-parsers.adoc delete mode 100644 modules/fts/pages/fts-default-settings.adoc delete mode 100644 modules/fts/pages/fts-index-analyzers.adoc delete mode 100644 modules/fts/pages/fts-index-partitions.adoc delete mode 100644 modules/fts/pages/fts-index-replicas.adoc delete mode 100644 modules/fts/pages/fts-index-type.adoc delete mode 100644 modules/fts/pages/fts-introduction.adoc delete mode 100644 modules/fts/pages/fts-manage-index-lifecycle.adoc delete mode 100644 modules/fts/pages/fts-multi-collection-behaviour.adoc delete mode 100644 modules/fts/pages/fts-perform-searches.adoc delete mode 100644 modules/fts/pages/fts-query-string-syntax-boosting.adoc delete mode 100644 modules/fts/pages/fts-query-string-syntax-date-ranges.adoc delete mode 100644 modules/fts/pages/fts-query-string-syntax-escaping.adoc delete mode 100644 modules/fts/pages/fts-query-string-syntax-field-scoping.adoc delete mode 100644 modules/fts/pages/fts-query-string-syntax-match-phrase.adoc delete mode 100644 modules/fts/pages/fts-query-string-syntax-match.adoc delete mode 100644 modules/fts/pages/fts-query-string-syntax-numeric-ranges.adoc delete mode 100644 modules/fts/pages/fts-query-string-syntax.adoc delete mode 100644 modules/fts/pages/fts-queryshape-circle.adoc delete mode 100644 modules/fts/pages/fts-queryshape-envelope.adoc delete mode 100644 modules/fts/pages/fts-queryshape-geometrycollection.adoc delete mode 100644 modules/fts/pages/fts-queryshape-linestring.adoc delete mode 100644 modules/fts/pages/fts-queryshape-multilinestring.adoc delete mode 100644 modules/fts/pages/fts-queryshape-multipoint.adoc delete mode 100644 modules/fts/pages/fts-queryshape-multipolygon.adoc delete mode 100644 modules/fts/pages/fts-queryshape-point.adoc delete mode 100644 modules/fts/pages/fts-queryshape-polygon.adoc delete mode 100644 modules/fts/pages/fts-quickstart-guide.adoc delete mode 100644 modules/fts/pages/fts-search-request.adoc delete mode 100644 modules/fts/pages/fts-searching-from-N1QL.adoc delete mode 100644 modules/fts/pages/fts-searching-from-the-UI.adoc delete mode 100644 modules/fts/pages/fts-searching-full-text-indexes-aliases.adoc delete mode 100644 modules/fts/pages/fts-searching-with-curl-http-requests.adoc delete mode 100644 modules/fts/pages/fts-searching-with-sdk.adoc delete mode 100644 modules/fts/pages/fts-secure-fts-queries.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-analytic-query.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-boolean-field-query.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-compound-query.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-conjuncts-disjuncts.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-date-range.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-fuzzy.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-geo-bounded-polygon.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-geo-bounded-rectangle.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-geo-point-distance.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-geojson-spatial.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-geopoint-spatial.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-geospatial.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-match-all.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-match-none.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-match-phrase.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-match.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-non-analytic-query.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-numeric-range.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-phrase.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-prefix-query.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-query-string-query.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-range-query.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-regexp.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-special-query.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-term-range.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-term.adoc delete mode 100644 modules/fts/pages/fts-supported-queries-wildcard.adoc delete mode 100644 modules/fts/pages/fts-supported-queries.adoc delete mode 100644 modules/fts/pages/fts-type-identifiers.adoc delete mode 100644 modules/fts/pages/fts-type-mapping-specifying-fields.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-Docid-with-regexp.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-add-child-field-analyzer.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-add-child-field-docvalues.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-add-child-field-field-name.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-add-child-field-field-searchable-as.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-add-child-field-field-type.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-add-child-field-include-in-all-field.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-add-child-field-include-term-vectors.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-add-child-field-index.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-add-child-field-store.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-add-child-field.adoc delete mode 100644 modules/fts/pages/fts-type-mappings-add-child-mappings.adoc delete mode 100644 modules/fts/pages/fts-type-mappings.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 91e9d3b64c..a6fa142cc2 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -17,7 +17,6 @@ include::develop:partial$nav.adoc[] include::tutorials:partial$nav.adoc[] include::guides:partial$nav.adoc[] -include::search:partial$nav.adoc[] * xref:home:ROOT:sdk.adoc[SDKs] ** xref:sdk-extensions::distributed-acid-transactions.adoc[Distributed ACID Transactions] @@ -29,112 +28,8 @@ include::search:partial$nav.adoc[] include::n1ql:partial$nav.adoc[] include::vector-search:partial$nav.adoc[] -* xref:fts:fts-introduction.adoc[Search] - ** xref:fts:fts-quickstart-guide.adoc[Quickstart Guide] - ** xref:fts:fts-creating-indexes.adoc[Create Search Indexes] - *** xref:fts:fts-creating-index-from-UI-quick-editor.adoc[Quick Editor and Example] - *** xref:fts:fts-creating-index-from-UI-classic-editor.adoc[Classic Editor and Examples] - **** Collections - ***** xref:fts:fts-creating-index-from-UI-classic-editor-onefield.adoc[One Field Index] - ***** xref:fts:fts-creating-index-from-UI-classic-editor-geopoint.adoc[Geopoint Index] - ***** xref:fts:fts-creating-index-from-UI-classic-editor-dynamic.adoc[Dynamic Index] - **** Bucket Compatibility - ***** xref:fts:fts-creating-index-from-UI-classic-editor-legacy.adoc[Legacy Index] - *** xref:fts:fts-creating-index-with-rest-api.adoc[REST API and Examples] - **** Collections - ***** xref:fts:fts-creating-index-from-REST-onefield.adoc[One Field Index] - ***** xref:fts:fts-creating-index-from-REST-geopoint.adoc[Geopoint Index] - ***** xref:fts:fts-creating-index-from-REST-dynamic.adoc[Dynamic Index] - ***** xref:fts:fts-creating-index-from-REST-geojson.adoc[GeoJSON Index] - **** Bucket Compatibility - ***** xref:fts:fts-creating-index-from-REST-legacy.adoc[Legacy Index] - *** xref:fts:fts-creating-index-from-UI-difference-between-classic-quick-editor.adoc[Comparing Editors and REST] - *** xref:fts:fts-configure-index-options.adoc[Configure Index Options] - **** xref:fts:fts-type-identifiers.adoc[Type Indentifiers] - **** xref:fts:fts-type-mappings.adoc[Type Mappings] - **** xref:fts:fts-index-analyzers.adoc[Index Analyzers] - **** xref:fts:fts-custom-filters.adoc[Custom Filters] - **** xref:fts:fts-date-time-parsers.adoc[Date Time Parsers] - **** xref:fts:fts-default-settings.adoc[Default Settings] - **** xref:fts:fts-index-replicas.adoc[Index Replicas] - **** xref:fts:fts-index-type.adoc[Index Type] - **** xref:fts:fts-index-partitions.adoc[Index Partitioning] - ** xref:fts:fts-creating-full-text-aliases.adoc[Create Index Alias] - ** xref:fts:fts-perform-searches.adoc[Perform Searches] - *** xref:fts:fts-searching-from-the-UI.adoc[Searching from the UI] - *** xref:fts:fts-searching-with-curl-http-requests.adoc[Searching using REST API] - **** xref:fts:fts-creating-with-curl-http-requests-json-structure.adoc[Request Structure] - **** xref:fts:fts-creating-with-curl-http-requests.adoc[Queries with Curl/HTTP Requests] - *** xref:fts:fts-searching-full-text-indexes-aliases.adoc[Searching Full Text Indexes/Aliases] - *** xref:fts:fts-multi-collection-behaviour.adoc[Searching Multi Collection Indexes] - *** xref:fts:fts-searching-with-sdk.adoc[Searching using SDK] - *** xref:fts:fts-secure-fts-queries.adoc[Searching Securely Using SSL] - *** xref:fts:fts-searching-from-N1QL.adoc[] - ** xref:fts:fts-search-request.adoc[Search Request] - ** xref:fts:fts-search-response.adoc[Search Response] - ** xref:fts:fts-manage-index-lifecycle.adoc[Manage Index Lifecycle] - ** xref:fts:fts-high-availability-for-search.adoc[High Availability for Search] - ** xref:fts:fts-supported-queries.adoc[Supported Queries] - *** xref:fts:fts-supported-queries-query-string-query.adoc[Query String Query] - **** xref:fts:fts-query-string-syntax.adoc[Query String Syntax] - ***** xref:fts:fts-query-string-syntax-boosting.adoc[Boosting] - ***** xref:fts:fts-query-string-syntax-date-ranges.adoc[Date Range] - ***** xref:fts:fts-query-string-syntax-escaping.adoc[Escaping] - ***** xref:fts:fts-query-string-syntax-field-scoping.adoc[Field Scoping] - ***** xref:fts:fts-query-string-syntax-match-phrase.adoc[Match Phrase] - ***** xref:fts:fts-query-string-syntax-match.adoc[Match Query Syntax] - ***** xref:fts:fts-query-string-syntax-numeric-ranges.adoc[Numeric Range] - *** xref:fts:fts-supported-queries-analytic-query.adoc[Analytic Queries] - **** xref:fts:fts-supported-queries-match.adoc[Match] - **** xref:fts:fts-supported-queries-match-phrase.adoc[Match Phrase] - *** xref:fts:fts-supported-queries-non-analytic-query.adoc[Non Analytic Queries] - **** xref:fts:fts-supported-queries-term.adoc[Term] - **** xref:fts:fts-supported-queries-phrase.adoc[Phrase] - **** xref:fts:fts-supported-queries-prefix-query.adoc[Prefix] - **** xref:fts:fts-supported-queries-regexp.adoc[Regexp] - **** xref:fts:fts-supported-queries-fuzzy.adoc[Fuzzy] - **** xref:fts:fts-supported-queries-wildcard.adoc[Wilcard] - *** xref:fts:fts-supported-queries-compound-query.adoc[Compound Queries] - **** xref:fts:fts-supported-queries-conjuncts-disjuncts.adoc[Conjuncts and Disjuncts] - **** xref:fts:fts-supported-queries-boolean-field-query.adoc[Boolean] - *** xref:fts:fts-supported-queries-range-query.adoc[Range Queries] - **** xref:fts:fts-supported-queries-numeric-range.adoc[Numeric Range] - **** xref:fts:fts-supported-queries-date-range.adoc[Date Range] - **** xref:fts:fts-supported-queries-term-range.adoc[Term Range] - *** xref:fts:fts-supported-queries-geospatial.adoc[Geo Spatial Queries] - **** xref:fts:fts-supported-queries-geopoint-spatial.adoc[Geopoint Queries] - ***** xref:fts:fts-supported-queries-geo-point-distance.adoc[Geopoint Distance] - ***** xref:fts:fts-supported-queries-geo-bounded-rectangle.adoc[Geopoint Bounded Rectangle] - ***** xref:fts:fts-supported-queries-geo-bounded-polygon.adoc[Geopoint Bounded Polygon] - **** xref:fts:fts-supported-queries-geojson-spatial.adoc[GeoJSON Queries] - ***** xref:fts:fts-queryshape-point.adoc[Point Query] - ***** xref:fts:fts-queryshape-linestring.adoc[LineString Query] - ***** xref:fts:fts-queryshape-polygon.adoc[Polygon Query] - ***** xref:fts:fts-queryshape-multipoint.adoc[MultiPoint Query] - ***** xref:fts:fts-queryshape-multilinestring.adoc[MultiLineString Query] - ***** xref:fts:fts-queryshape-multipolygon.adoc[MultiPolygon Query] - ***** xref:fts:fts-queryshape-geometrycollection.adoc[GeometryCollection Query] - ***** xref:fts:fts-queryshape-circle.adoc[Circle Query] - ***** xref:fts:fts-queryshape-envelope.adoc[Envelope Query] - *** xref:fts:fts-supported-queries-special-query.adoc[Special Queries] - **** xref:fts:fts-supported-queries-match-all.adoc[Match All] - **** xref:fts:fts-supported-queries-match-none.adoc[Match None] - ** xref:fts:fts-architecture.adoc[Search Service Architecture] - *** xref:fts:fts-architecture-scatter-gather.adoc[Scatter Gather] - *** xref:fts:fts-architecture-ports-used.adoc[Ports Used By FTS] - *** xref:fts:fts-rebalance-failover.adoc[Rebalance/Failover] - ** xref:fts:fts-cluster-options.adoc[Cluster Level Options] - *** xref:fts:fts-advanced-settings-bleveMaxResultWindow.adoc[bleveMaxResultWindow] - *** xref:fts:fts-advanced-settings-bleveMaxClauseCount.adoc[bleveMaxClauseCount] - *** xref:fts:fts-advanced-settings-maxFeedsPerDCPAgent.adoc[maxFeedsPerDCPAgent] - *** xref:fts:fts-advance-settings-maxConcurrentPartitionMovesPerNode.adoc[maxConcurrentPartitionMovesPerNode] - *** xref:fts:fts-advanced-settings-enableVerboseLogging.adoc[enableVerboseLogging] - *** xref:fts:fts-advanced-settings-ftsMemoryQuota.adoc[ftsMemoryQuota] - *** xref:fts:fts-advanced-settings-maxReplicasAllowed.adoc[maxReplicasAllowed] - *** xref:fts:fts-advanced-settings-slowQueryLogTimeout.adoc[slowQueryLogTimeout] - *** xref:fts:fts-advanced-settings-CBFT-ENV-OPTIONS.adoc[CBFT_ENV_OPTIONS] - ** xref:fts:fts-monitor.adoc[Statistics and Monitoring] - ** xref:fts:fts-troubleshooting.adoc[Troubleshooting and FAQs] +include::search:partial$nav.adoc[] + * xref:eventing:eventing-overview.adoc[Eventing] ** xref:eventing:eventing-Terminologies.adoc[Terminology] ** xref:eventing:eventing-language-constructs.adoc[Language Constructs] diff --git a/modules/fts/pages/fts-configure-index-options.adoc b/modules/fts/pages/fts-configure-index-options.adoc deleted file mode 100644 index b37c59498c..0000000000 --- a/modules/fts/pages/fts-configure-index-options.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= Configure Index Options - -In Full Text Search, you can create an index just by specifying the index name and selecting the source bucket, scope and collection for the index. However, FTS provides various configurations for the index to enhance the search experience. - -While creating an index or after creating an index, you can configure various options for your index. Based on the configuration of the index, a user can search in a more selective and efficient manner. - -The various configuration options for Full Text Index are as follows: - -* xref:fts-type-identifiers.adoc[Type Identifiers] -* xref:fts-type-mappings.adoc[Type Mappings] -* xref:fts-index-analyzers.adoc[Index Analyzers] -* xref:fts-custom-filters.adoc[Custom Filters] -* xref:fts-date-time-parsers.adoc[Date Time Parsers] -* xref:fts-default-settings.adoc[Default Settings] -* xref:fts-index-replicas.adoc[Index Replicas] -* xref:fts-index-type.adoc[Index Type] -* xref:fts-index-partitions.adoc[Index Partitioning] \ No newline at end of file diff --git a/modules/fts/pages/fts-creating-full-text-aliases.adoc b/modules/fts/pages/fts-creating-full-text-aliases.adoc deleted file mode 100644 index dce0fc0cb2..0000000000 --- a/modules/fts/pages/fts-creating-full-text-aliases.adoc +++ /dev/null @@ -1,27 +0,0 @@ -= Creating Index Alias - -[abstract] -Full Text Index Alias is the name that can be used in place of the actual full text index name. You can perform the searches across multiple buckets and multiple scopes by means of index aliases. - -An index alias points to one or more Full Text Indexes or to additional aliases: its purpose is therefore somewhat comparable to that of a symbolic link in a filesystem. Queries on an index alias are performed on all ultimate targets, and merged results are provided. - -The use of index aliases permits indirection in naming, whereby applications refer to an alias-name that never changes, leaving administrators free periodically to change the identity of the real index pointed to by the alias. This may be particularly useful when an index needs to be updated: to avoid down-time, while the current index remains in service, a clone of the current index can be created, modified, and tested. Then, when the clone is ready, the existing alias can be retargeted so that the clone becomes the current index; and the (now) previous index can be removed. - -The following process explains how to create an index alias in Couchbase: - -Access the couchbase application. In the left pane, click *Search*. The Full Text Aliases panel is shown at the bottom of the page. - -[#fts_full_text_aliases_panel] -image::fts-full-text-aliases-panel.png[,700,align=left] - -Now, click *+ Add Alias* to add new alias. The Add Alias page opens. - -[#fts_add_alias_screen] -image::fts-add-alias-screen.png[,620,align=left] - -In the Add Alias page, add the alias name in the *Index Name* field. After that select one or more indexes from the *Target Indexes* list for which you want to add an alias. The selected index is highlighted in a separate color. - -Finally, click *Create Index Alias*. The new index alias is added to the list in the Full Text Aliases panel. - -[#fts_add_alias_page_with_alias] -image::fts-full-text-aliases-page-with-alias.png[,700,align=left] \ No newline at end of file diff --git a/modules/fts/pages/fts-creating-index-from-REST-dynamic.adoc b/modules/fts/pages/fts-creating-index-from-REST-dynamic.adoc deleted file mode 100644 index db6ab47a21..0000000000 --- a/modules/fts/pages/fts-creating-index-from-REST-dynamic.adoc +++ /dev/null @@ -1,219 +0,0 @@ -= Creating a Dynamic Index via the REST API - -This example quickly creates the same index as xref:fts-creating-index-from-UI-classic-editor-dynamic.adoc#main[Creating a Dynamic Index via the UI]. - -The cURL command below was initially created via the Classic Editor in the UI, however the follwoing modifications were made. - -* The curl flag "*-s*" to suppress some runtime output. - -* The credentials "*-u :*" were altered to "*-u* $*{CB_USERNAME}*:$*{CB_PASSWORD}*". - -* The hostname or IP address was replaced with $*{CB_HOSTNAME}*. - -* The commands output is piped through the utility *http://stedolan.github.io/jq[jq]* to enhance readability. - -* The two (2) UUIDs were removed (similar to the below) because we want to make a new index not modify an existing one. -+ -[source, json] ----- - "uuid": "273a60635f5248e5", - "sourceUUID": "2b421d183cb76aebbffa45424736ec2e", ----- - -= The Creation Command - -The full command to create the index is below and can be executed verbatim if you have the environment variable $*{CB_USERNAME}*, $*{CB_PASSWORD}* and $*{CB_HOSTNAME}* set. - -[source, command] ----- -curl -s -XPUT -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_dynamic -d \ -'{ - "type": "fulltext-index", - "name": "test_dynamic", - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "planParams": { - "maxPartitionsPerPIndex": 1024, - "indexPartitions": 1 - }, - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "", - "mode": "scope.collection.type_field", - "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": { - "_default._default": { - "dynamic": true, - "enabled": true - } - } - }, - "store": { - "indexType": "scorch", - "segmentVersion": 15 - } - }, - "sourceParams": {} -}' | jq . ----- - -If you successfully create the index you should a response liekt the follwoing - -[source, json] ----- -{ - "status": "ok", - "uuid": "56304e8bab69bc99" -} ----- - -== Test the Dynamic Index with a simple query - -Request the first 10 item closet to a longitude of `-2.235143` and a latitude of `53.482358`. -The target-field `geo` is specified, as is a `distance` of `100` miles: this is the radius within which target-locations must reside for their documents to be returned. Don't worry about newlines when you paste the text. - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_dynamic/query \ --d '{ - "query": { - "query": "+view +food +beach" - }, - "size": 10, - "from": 0 -}' | jq . ----- - -The output of a ten (10) hits (from a total of 121 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "query": "+view +food +beach" - }, - "size": 10, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "-_score" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_dynamic_56304e8bab69bc99_4c1c5584", - "id": "landmark_38035", - "score": 1.1579735254455, - "sort": [ - "_score" - ] - }, - { - "index": "test_dynamic_56304e8bab69bc99_4c1c5584", - "id": "landmark_4428", - "score": 1.0216606971061395, - "sort": [ - "_score" - ] - }, - { - "index": "test_dynamic_56304e8bab69bc99_4c1c5584", - "id": "landmark_26385", - "score": 0.8510363574544033, - "sort": [ - "_score" - ] - }, - { - "index": "test_dynamic_56304e8bab69bc99_4c1c5584", - "id": "hotel_6169", - "score": 0.6627638582612397, - "sort": [ - "_score" - ] - }, - { - "index": "test_dynamic_56304e8bab69bc99_4c1c5584", - "id": "hotel_15914", - "score": 0.6488767405998539, - "sort": [ - "_score" - ] - }, - { - "index": "test_dynamic_56304e8bab69bc99_4c1c5584", - "id": "hotel_15917", - "score": 0.6408954058353277, - "sort": [ - "_score" - ] - }, - { - "index": "test_dynamic_56304e8bab69bc99_4c1c5584", - "id": "hotel_35855", - "score": 0.5994386303570878, - "sort": [ - "_score" - ] - }, - { - "index": "test_dynamic_56304e8bab69bc99_4c1c5584", - "id": "hotel_21855", - "score": 0.5876768363989866, - "sort": [ - "_score" - ] - }, - { - "index": "test_dynamic_56304e8bab69bc99_4c1c5584", - "id": "hotel_21889", - "score": 0.5815097705436758, - "sort": [ - "_score" - ] - }, - { - "index": "test_dynamic_56304e8bab69bc99_4c1c5584", - "id": "hotel_5080", - "score": 0.5795265708969183, - "sort": [ - "_score" - ] - } - ], - "total_hits": 121, - "max_score": 1.1579735254455, - "took": 916181, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-creating-index-from-REST-geojson.adoc b/modules/fts/pages/fts-creating-index-from-REST-geojson.adoc deleted file mode 100644 index b5ac2345a6..0000000000 --- a/modules/fts/pages/fts-creating-index-from-REST-geojson.adoc +++ /dev/null @@ -1,339 +0,0 @@ -= Creating a GeoJSON Index via the REST API - -This example quickly creates the final index (able to sort by keyword) as found in xref:fts-supported-queries-geojson-spatial.adoc#creating_a_geojson_index[Creating a Geospatial Index (type geojson)] in Geospatial GeoJSON Queries. - -[NOTE] -In order to run this example there is a required data modification for `travel-sample` refer to the "Prerequisites - Modify the travel-sample dataset" section in xref:fts-supported-queries-geojson-spatial.adoc#prerequisites-dataset[Geospatial GeoJSON Queries]. - -The cURL command below was initially created via the Classic Editor in the UI, however the follwoing modifications were made. - -* The curl flag "*-s*" to suppress some runtime output. - -* The credentials "*-u :*" were altered to "*-u* $*{CB_USERNAME}*:$*{CB_PASSWORD}*". - -* The hostname or IP address was replaced with $*{CB_HOSTNAME}*. - -* The commands output is piped through the utility *http://stedolan.github.io/jq[jq]* to enhance readability. - -* The two (2) UUIDs were removed (similar to the below) because we want to make a new index not modify an existing one. -+ -[source, json] ----- - "uuid": "273a60635f5248e5", - "sourceUUID": "2b421d183cb76aebbffa45424736ec2e", ----- - -== The Creation Command - -The full command to create the index is below and can be executed verbatim if you have the environment variable $*{CB_USERNAME}*, $*{CB_PASSWORD}* and $*{CB_HOSTNAME}* set. - -[source, command] ----- -curl -s -XPUT -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson -d \ -'{ - "type": "fulltext-index", - "name": "test_geojson", - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "planParams": { - "maxPartitionsPerPIndex": 1024, - "indexPartitions": 1 - }, - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "", - "mode": "scope.collection.type_field", - "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": { - "_default._default": { - "dynamic": true, - "enabled": true, - "properties": { - "airportname": { - "dynamic": false, - "enabled": true, - "fields": [ - { - "analyzer": "keyword", - "include_in_all": true, - "index": true, - "name": "name", - "store": true, - "type": "text" - } - ] - }, - "geoarea": { - "dynamic": false, - "enabled": true, - "fields": [ - { - "include_in_all": true, - "index": true, - "name": "geoarea", - "type": "geoshape" - } - ] - }, - "geojson": { - "dynamic": false, - "enabled": true, - "fields": [ - { - "include_in_all": true, - "index": true, - "name": "geojson", - "type": "geoshape" - } - ] - }, - "name": { - "dynamic": false, - "enabled": true, - "fields": [ - { - "analyzer": "keyword", - "include_in_all": true, - "index": true, - "name": "name", - "store": true, - "type": "text" - } - ] - } - } - } - } - }, - "store": { - "indexType": "scorch", - "segmentVersion": 15 - } - }, - "sourceParams": {} -}' | jq . ----- - -If you successfully create the index you should a response liekt the follwoing - -[source, json] ----- -{ - "status": "ok", - "uuid": "690ac8f8179a4a86" -} ----- - -== Test the GeoJSON Index with a simple query - -Request the first 10 items within the state of Utah (note the query body consistes of simple set of hand drawn set of corner points). -The target-field `geojson` is specified, to be compared to the query Polygon the target-locations must reside for their documents to be returned. -Don't worry about newlines when you paste the text. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "geometry": { - "shape": { - "coordinates": [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ], - "type": "Polygon" - }, - "relation": "within" - }, - "field": "geojson" - }, - "size": 10, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of ten (10) hits (from a total of 18 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [ - [ - -114.027099609375, - 42.00848901572399 - ], - [ - -114.04907226562499, - 36.99377838872517 - ], - [ - -109.05029296875, - 36.99377838872517 - ], - [ - -109.05029296875, - 40.98819156349393 - ], - [ - -111.060791015625, - 40.98819156349393 - ], - [ - -111.02783203125, - 42.00848901572399 - ], - [ - -114.027099609375, - 42.00848901572399 - ] - ] - ] - }, - "relation": "within" - }, - "field": "geojson" - }, - "size": 10, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_6999", - "score": 0.13231342774148913, - "sort": [ - "Brigham City" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7857", - "score": 0.27669394470240527, - "sort": [ - "Bryce Canyon" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7074", - "score": 0.13231342774148913, - "sort": [ - "Canyonlands Field" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7583", - "score": 0.13231342774148913, - "sort": [ - "Carbon County Regional-Buck Davis Field" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_3824", - "score": 0.24860341896785076, - "sort": [ - "Cedar City Rgnl" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7581", - "score": 0.13231342774148913, - "sort": [ - "Delta Municipal Airport" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_8803", - "score": 0.13231342774148913, - "sort": [ - "Heber City Municipal Airport" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_3614", - "score": 0.13231342774148913, - "sort": [ - "Hill Afb" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_9279", - "score": 0.27669394470240527, - "sort": [ - "Hite Airport" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_6998", - "score": 0.13231342774148913, - "sort": [ - "Logan-Cache" - ] - } - ], - "total_hits": 18, - "max_score": 0.27669394470240527, - "took": 18446484, - "facets": null -} ----- - -== The Index if viewed in the UI's Classic Editor - -image::fts-geojson-mod-index-full.png[,600,align=left] diff --git a/modules/fts/pages/fts-creating-index-from-REST-geopoint.adoc b/modules/fts/pages/fts-creating-index-from-REST-geopoint.adoc deleted file mode 100644 index 1834c51a47..0000000000 --- a/modules/fts/pages/fts-creating-index-from-REST-geopoint.adoc +++ /dev/null @@ -1,263 +0,0 @@ -= Creating a Geopoint Index via the REST API - -This example quickly creates the same index as xref:fts-creating-index-from-UI-classic-editor-geopoint.adoc#main[Creating a Geopoint Index via the UI]. - -The cURL command below was initially created via the Classic Editor in the UI, however the follwoing modifications were made. - -* The curl flag "*-s*" to suppress some runtime output. - -* The credentials "*-u :*" were altered to "*-u* $*{CB_USERNAME}*:$*{CB_PASSWORD}*". - -* The hostname or IP address was replaced with $*{CB_HOSTNAME}*. - -* The commands output is piped through the utility *http://stedolan.github.io/jq[jq]* to enhance readability. - -* The two (2) UUIDs were removed (similar to the below) because we want to make a new index not modify an existing one. -+ -[source, json] ----- - "uuid": "273a60635f5248e5", - "sourceUUID": "2b421d183cb76aebbffa45424736ec2e", ----- - -= The Creation Command - -The full command to create the index is below and can be executed verbatim if you have the environment variable $*{CB_USERNAME}*, $*{CB_PASSWORD}* and $*{CB_HOSTNAME}* set. - -[source, command] ----- -curl -s -XPUT -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geopoint -d \ -'{ - "type": "fulltext-index", - "name": "test_geopoint", - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "planParams": { - "maxPartitionsPerPIndex": 1024, - "indexPartitions": 1 - }, - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "", - "mode": "scope.collection.type_field", - "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": { - "_default._default": { - "dynamic": true, - "enabled": true, - "properties": { - "geo": { - "dynamic": false, - "enabled": true, - "fields": [ - { - "include_in_all": true, - "index": true, - "name": "geo", - "type": "geopoint" - } - ] - } - } - } - } - }, - "store": { - "indexType": "scorch", - "segmentVersion": 15, - "spatialPlugin": "s2" - } - }, - "sourceParams": {} -}' | jq . ----- - -If you successfully create the index you should a response liekt the follwoing - -[source, json] ----- -{ - "status": "ok", - "uuid": "274e2bf04ddc8d3e" -} ----- - -== Test the Geopoint Index with a simple query - -Request the first 10 item closet to a longitude of `-2.235143` and a latitude of `53.482358`. -The target-field `geo` is specified, as is a `distance` of `100` miles: this is the radius within which target-locations must reside for their documents to be returned. Don't worry about newlines when you paste the text. - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geopoint/query \ --d '{ - "from": 0, - "size": 10, - "query": { - "location": { - "lon": -2.235143, - "lat": 53.482358 - }, - "distance": "100mi", - "field": "geo" - }, - "sort": [ - { - "by": "geo_distance", - "field": "geo", - "unit": "mi", - "location": { - "lon": -2.235143, - "lat": 53.482358 - } - } - ] -}' | jq . ----- - -The output of a ten (10) hits (from a total of 847 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "location": [ - -2.235143, - 53.482358 - ], - "distance": "100mi", - "field": "geo" - }, - "size": 10, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - { - "by": "geo_distance", - "field": "geo", - "location": { - "lat": 53.482358, - "lon": -2.235143 - }, - "unit": "mi" - } - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geopoint_274e2bf04ddc8d3e_4c1c5584", - "id": "landmark_17411", - "score": 0.025840756648257503, - "sort": [ - " \u0001?E#9>N\f\"e" - ] - }, - { - "index": "test_geopoint_274e2bf04ddc8d3e_4c1c5584", - "id": "landmark_17409", - "score": 0.025840756648257503, - "sort": [ - " \u0001?O~i*(kD," - ] - }, - { - "index": "test_geopoint_274e2bf04ddc8d3e_4c1c5584", - "id": "landmark_17403", - "score": 0.025840756648257503, - "sort": [ - " \u0001?Sg*|/t\u001f\u0002" - ] - }, - { - "index": "test_geopoint_274e2bf04ddc8d3e_4c1c5584", - "id": "hotel_17413", - "score": 0.025840756648257503, - "sort": [ - " \u0001?U]S\\.e\u0002_" - ] - }, - { - "index": "test_geopoint_274e2bf04ddc8d3e_4c1c5584", - "id": "hotel_17414", - "score": 0.025840756648257503, - "sort": [ - " \u0001?Z\u0000./\u0007Q\u0012\t" - ] - }, - { - "index": "test_geopoint_274e2bf04ddc8d3e_4c1c5584", - "id": "landmark_17410", - "score": 0.025840756648257503, - "sort": [ - " \u0001?Z3T6 \u0010\u0019@" - ] - }, - { - "index": "test_geopoint_274e2bf04ddc8d3e_4c1c5584", - "id": "landmark_17412", - "score": 0.025840756648257503, - "sort": [ - " \u0001?]-\u000fm?\u000b\u0014#" - ] - }, - { - "index": "test_geopoint_274e2bf04ddc8d3e_4c1c5584", - "id": "landmark_17408", - "score": 0.025840756648257503, - "sort": [ - " \u0001?^DV7\u0014t:^" - ] - }, - { - "index": "test_geopoint_274e2bf04ddc8d3e_4c1c5584", - "id": "landmark_17406", - "score": 0.025840756648257503, - "sort": [ - " \u0001?_<\u00009\u001eW\u0013\u0012" - ] - }, - { - "index": "test_geopoint_274e2bf04ddc8d3e_4c1c5584", - "id": "landmark_17397", - "score": 0.025840756648257503, - "sort": [ - " \u0001?c\u001cx\u0010n\u0016Wl" - ] - } - ], - "total_hits": 847, - "max_score": 0.2099587543053028, - "took": 69084563, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-creating-index-from-REST-legacy.adoc b/modules/fts/pages/fts-creating-index-from-REST-legacy.adoc deleted file mode 100644 index 10264e23f5..0000000000 --- a/modules/fts/pages/fts-creating-index-from-REST-legacy.adoc +++ /dev/null @@ -1,214 +0,0 @@ -= Creating a Legacy Index via the REST API - -This example quickly creates the same index as xref:fts-creating-index-from-UI-classic-editor-legacy.adoc#main[Creating a Legacy Index via the UI]. - -The cURL command below was initially created via the Classic Editor in the UI, however the follwoing modifications were made. - -* The curl flag "*-s*" to suppress some runtime output. - -* The credentials "*-u :*" were altered to "*-u* $*{CB_USERNAME}*:$*{CB_PASSWORD}*". - -* The hostname or IP address was replaced with $*{CB_HOSTNAME}*. - -* The commands output is piped through the utility *http://stedolan.github.io/jq[jq]* to enhance readability. - -* The two (2) UUIDs were removed (similar to the below) because we want to make a new index not modify an existing one. -+ -[source, json] ----- - "uuid": "273a60635f5248e5", - "sourceUUID": "2b421d183cb76aebbffa45424736ec2e", ----- - -= The Creation Command - -The full command to create the index is below and can be executed verbatim if you have the environment variable $*{CB_USERNAME}*, $*{CB_PASSWORD}* and $*{CB_HOSTNAME}* set. - -_Note a legacy index can only work on just one keyspace ._default._default._ - -[source, command] ----- -curl -s -XPUT -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/travel-sample-index -d \ -'{ - "type": "fulltext-index", - "name": "travel-sample-index", - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "planParams": { - "maxPartitionsPerPIndex": 1024, - "indexPartitions": 1 - }, - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "", - "mode": "type_field", - "type_field": "type" - }, - "mapping": { - "analysis": {}, - "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 - } - }, - "sourceParams": {} -}' | jq . ----- - -If you successfully create the index you should a response liekt the follwoing - -[source, json] ----- -{ - "status": "ok", - "uuid": "20fcc810e312083b -} ----- - -== Test the Legacy Index with a simple query - -Request the first 10 items where the content field in the collection `travel-sample`_default._default has documents with: "view", "food", and "beach" - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/travel-sample-index/query \ --d '{ - "query": { - "query": "+view +food +beach" - }, - "size": 10, - "from": 0 -}' | jq . ----- - -The output of a ten (10) hits (from a total of 121 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "query": "+view +food +beach" - }, - "size": 10, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "-_score" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "travel-sample-index_20fcc810e312083b_4c1c5584", - "id": "landmark_38035", - "score": 1.1579735254455, - "sort": [ - "_score" - ] - }, - { - "index": "travel-sample-index_20fcc810e312083b_4c1c5584", - "id": "landmark_4428", - "score": 1.0216606971061395, - "sort": [ - "_score" - ] - }, - { - "index": "travel-sample-index_20fcc810e312083b_4c1c5584", - "id": "landmark_26385", - "score": 0.8510363574544033, - "sort": [ - "_score" - ] - }, - { - "index": "travel-sample-index_20fcc810e312083b_4c1c5584", - "id": "hotel_6169", - "score": 0.6627638582612397, - "sort": [ - "_score" - ] - }, - { - "index": "travel-sample-index_20fcc810e312083b_4c1c5584", - "id": "hotel_15914", - "score": 0.6488767405998539, - "sort": [ - "_score" - ] - }, - { - "index": "travel-sample-index_20fcc810e312083b_4c1c5584", - "id": "hotel_15917", - "score": 0.6408954058353277, - "sort": [ - "_score" - ] - }, - { - "index": "travel-sample-index_20fcc810e312083b_4c1c5584", - "id": "hotel_35855", - "score": 0.5994386303570878, - "sort": [ - "_score" - ] - }, - { - "index": "travel-sample-index_20fcc810e312083b_4c1c5584", - "id": "hotel_21855", - "score": 0.5876768363989866, - "sort": [ - "_score" - ] - }, - { - "index": "travel-sample-index_20fcc810e312083b_4c1c5584", - "id": "hotel_21889", - "score": 0.5815097705436758, - "sort": [ - "_score" - ] - }, - { - "index": "travel-sample-index_20fcc810e312083b_4c1c5584", - "id": "hotel_5080", - "score": 0.5795265708969183, - "sort": [ - "_score" - ] - } - ], - "total_hits": 121, - "max_score": 1.1579735254455, - "took": 1479872, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-creating-index-from-REST-onefield.adoc b/modules/fts/pages/fts-creating-index-from-REST-onefield.adoc deleted file mode 100644 index cbbc4f695c..0000000000 --- a/modules/fts/pages/fts-creating-index-from-REST-onefield.adoc +++ /dev/null @@ -1,374 +0,0 @@ -= Creating a One Field Index via the REST API - -This example quickly creates the same index as xref:fts-creating-index-from-UI-classic-editor-onefield.adoc#main[Creating a One Field Index via the UI]. - -The cURL command below was initially created via the Classic Editor in the UI, however the follwoing modifications were made. - -* The curl flag "*-s*" to suppress some runtime output. - -* The credentials "*-u :*" were altered to "*-u* $*{CB_USERNAME}*:$*{CB_PASSWORD}*". - -* The hostname or IP address was replaced with $*{CB_HOSTNAME}*. - -* The commands output is piped through the utility *http://stedolan.github.io/jq[jq]* to enhance readability. - -* The two (2) UUIDs were removed (similar to the below) because we want to make a new index not modify an existing one. -+ -[source, json] ----- - "uuid": "273a60635f5248e5", - "sourceUUID": "2b421d183cb76aebbffa45424736ec2e", ----- - -= The Creation Command - -The full command to create the index is below and can be executed verbatim if you have the environment variable $*{CB_USERNAME}*, $*{CB_PASSWORD}* and $*{CB_HOSTNAME}* set. - -[source, command] ----- -curl -s -XPUT -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/landmark-content-index -d \ -'{ - "type": "fulltext-index", - "name": "landmark-content-index", - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "planParams": { - "maxPartitionsPerPIndex": 1024, - "indexPartitions": 1 - }, - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "", - "mode": "scope.collection.type_field", - "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.landmark": { - "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" - } - ] - } - } - } - } - }, - "store": { - "indexType": "scorch", - "segmentVersion": 15 - } - }, - "sourceParams": {} -}' | jq . ----- - -If you successfully create the index you should a response liekt the follwoing - -[source, json] ----- -{ - "status": "ok", - "uuid": "22ab3f601349af9d" -} ----- - -== Test the One Field Index with a simple query - -Request the first 10 items where the content field in the collection `travel-sample`.inventory.landmark has documents with: "view", "food", and "beach" - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/landmark-content-index/query \ --d '{ - "query": { - "query": "+view +food +beach" - }, - "size": 10, - "from": 0 -}' | jq . ----- - -The output of a three (3) hits (from a total of 3 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "query": "+view +food +beach" - }, - "size": 10, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "-_score" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "landmark-content-index_22ab3f601349af9d_4c1c5584", - "id": "landmark_4428", - "score": 2.425509689250102, - "sort": [ - "_score" - ] - }, - { - "index": "landmark-content-index_22ab3f601349af9d_4c1c5584", - "id": "landmark_26385", - "score": 1.6270812956011347, - "sort": [ - "_score" - ] - }, - { - "index": "landmark-content-index_22ab3f601349af9d_4c1c5584", - "id": "landmark_38035", - "score": 1.1962539437368078, - "sort": [ - "_score" - ] - } - ], - "total_hits": 3, - "max_score": 2.425509689250102, - "took": 289005, - "facets": null -} ----- - -== Test the One Field Index with a more complex query - -Request the first 10 items where the content field in the collection `travel-sample`.inventory.landmark has documents with: "view", "food", and "beach". -However in this case we will display any fields and highlight text, this is possible because of the features we put into the index. - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/landmark-content-index/query \ --d '{ - "fields": [ - "*" - ], - "highlight": {}, - "query": { - "query": "+view +food +beach" - }, - "size": 10, - "from": 0 -}' | jq . ----- - -The output of a total of three (3) hits is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "query": "+view +food +beach" - }, - "size": 10, - "from": 0, - "highlight": { - "style": null, - "fields": null - }, - "fields": [ - "*" - ], - "facets": null, - "explain": false, - "sort": [ - "-_score" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "landmark-content-index_22ab3f601349af9d_4c1c5584", - "id": "landmark_4428", - "score": 2.425509689250102, - "locations": { - "content": { - "beach": [ - { - "pos": 11, - "start": 61, - "end": 66, - "array_positions": null - } - ], - "food": [ - { - "pos": 3, - "start": 13, - "end": 17, - "array_positions": null - } - ], - "view": [ - { - "pos": 8, - "start": 46, - "end": 50, - "array_positions": null - } - ] - } - }, - "fragments": { - "content": [ - "serves fresh food at very reasonable prices - view of stoney beach with herons" - ] - }, - "sort": [ - "_score" - ], - "fields": { - "content": "serves fresh food at very reasonable prices - view of stoney beach with herons" - } - }, - { - "index": "landmark-content-index_22ab3f601349af9d_4c1c5584", - "id": "landmark_26385", - "score": 1.6270812956011347, - "locations": { - "content": { - "beach": [ - { - "pos": 25, - "start": 127, - "end": 132, - "array_positions": null - } - ], - "food": [ - { - "pos": 17, - "start": 90, - "end": 94, - "array_positions": null - } - ], - "view": [ - { - "pos": 34, - "start": 169, - "end": 173, - "array_positions": null - } - ] - } - }, - "fragments": { - "content": [ - "Burgers, seafood, and other simple but tasty meals right at the harbor. You can take your food around the corner to sit on the beach or the sea wall and enjoy the ocean view while you eat." - ] - }, - "sort": [ - "_score" - ], - "fields": { - "content": "Burgers, seafood, and other simple but tasty meals right at the harbor. You can take your food around the corner to sit on the beach or the sea wall and enjoy the ocean view while you eat." - } - }, - { - "index": "landmark-content-index_22ab3f601349af9d_4c1c5584", - "id": "landmark_38035", - "score": 1.1962539437368078, - "locations": { - "content": { - "beach": [ - { - "pos": 17, - "start": 86, - "end": 91, - "array_positions": null - } - ], - "food": [ - { - "pos": 50, - "start": 280, - "end": 284, - "array_positions": null - } - ], - "view": [ - { - "pos": 30, - "start": 169, - "end": 173, - "array_positions": null - } - ] - } - }, - "fragments": { - "content": [ - "⦠Beach distillery offers a full menu, Sunday brunch, drinks, and a tremendous ocean view with comfortable fire pits. Happy hour Mon-Fri from 5PM to 7PM offers half-priced drinks and a discounted food â¦" - ] - }, - "sort": [ - "_score" - ], - "fields": { - "content": "Famous for "the Blue Lady", a ghost rumored to haunt the premises, the Moss Beach distillery offers a full menu, Sunday brunch, drinks, and a tremendous ocean view with comfortable fire pits. Happy hour Mon-Fri from 5PM to 7PM offers half-priced drinks and a discounted food menu." - } - } - ], - "total_hits": 3, - "max_score": 2.425509689250102, - "took": 410110, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-creating-index-from-UI-classic-editor-dynamic.adoc b/modules/fts/pages/fts-creating-index-from-UI-classic-editor-dynamic.adoc deleted file mode 100644 index 8e58306dc0..0000000000 --- a/modules/fts/pages/fts-creating-index-from-UI-classic-editor-dynamic.adoc +++ /dev/null @@ -1,103 +0,0 @@ -= Classic Editor - -[abstract] - -The classic editor is the most advanced tool where users can directly configure the index mapping with all capabilities. - -You can build the exact same index via the command line use the REST API, refer to xref:fts-creating-index-from-REST-dynamic.adoc[Creating a Dynamic Index via the REST API]. - -This section introduces index creations via a step by step walk through using the classic editor. The reader should be already familiar with the basic concepts of full-text search - -This example xref:fts-creating-index-from-UI-classic-editor-dynamic.adoc#main[Creating a Dynamic Index] covers creating an index that dynamically indexes every field in a collection. - -[#main] - -= Creating a Dynamic Index - -This section describes creating and Index on a bucket's collection across *all fields in the a collection*. - -This is equivalent to the xref:fts-creating-index-from-UI-classic-editor-legacy.adoc#main[Creating a Legacy Index]. - -To create the desired index through the Classic Editor: - -* Access the *Couchbase Web Console* > *Search* page. -+ -image::fts-search-page.png[,,align=left] - -* Click the *Add Index* link in the upper right of the *Couchbase Web Console* > *Search* page. -+ -image::fts-add-initial.png[,600,align=left] - -* To define any index on which Full Text Search a unique name for the index in the *Index Name* field, on the upper-left. Note that only alphanumeric characters, hyphens, and underscores are allowed for index names and the first character of the name must be alphabetic. -+ -Enter *test_dynamic* as the name of the Search index you are creating in the *Index Name* text-box. -+ -image::fts-index-name-dynamic.png[,450,align=left] - -* Select the bucket *travel-sample* from the *Bucket* pull-down menu. -+ -Use the pull-down menu provided for the Bucket field, on the upper-right, and select a bucket that you are allowed to access to via the cluster's RBAC settings. -+ -image::fts-index-name-and-bucket-dynamic.png[,450,align=left] - -* Select the checkbox *[X] Use non-default scope/collections* -+ -This allows your index to stream mutations from one or more non-default collections under the selected bucket and scope. -+ -image::fts-select-dynamic-scope-collections.png[,450,align=left] - -* You will see a newly visible pull-down menu provided for the *Scope* field, under the *[X] Use non-default scope/collections* checkbox, and select a bucket that you are allowed to access to via the cluster's RBAC settings. -+ -For this example leave the setting as *_default* which which is used to migrate bucket based data into the collections paradigm. - -* Under *Type Mapings*, unselect the checkbox *[ ] default | dynamic*. -+ -This is required as this type mapping (the default mapping) is only valid for the ._default._default which is typically used to upgrade a 6.X server from a bucket into a more powerful collections paradigm. In this example we will do the equivlent but on a per collections basis. -+ -image::fts-uncheck-default-mapping.png[,600,align=left] - -* Click on the button *+ Add Type Mapping* - -** A new section with a *Collection* pull-down, *Analyzer* pull-down and a *[ ] only index specified fields* checkbox will appear. -+ -image::fts-index-menu1-nondefault-empty.png[,600,align=left] - -** Select *_default* from the *Collection* pull-down, note the pull down will change to a text field prefilled with *_default._default* -+ -image::fts-index-menu1-geopoint-filled.png[,600,align=left] - -** Leave the *[{nbsp}{nbsp}] only index specified fields* checkbox blank or unset. -+ -This will index all fields in the scope *_default* collection *_default*, howver not this is not recommended for large production datasets. - -** Click on the blue *ok* at the right of the section to save this mapping. - -* Save your index, left-click on the *Create Index* button near the bottom of the screen. -+ -This is all you need to specify in order to create a more advanced index for test and development. No further configuration is required. -+ -image::fts-index-create-button.png[,450,align=left] - -* If you subsequently Edit your Index it should look like the following: -+ -image::fts-edit-index-dynamic.png[,600,align=left] - -NOTE: Indexing all fields as above indexes across all fields is not recommended for production environments since it creates indexes that may be unnecessarily large, and therefore insufficiently performant. - -== Test the Dynamic Index with a simple query - -In the *Couchbase Web Console* > *Search* page. - -* Click on the index you just created (named "landmark-content-index") to expand the Index's controls. - -* In the text area of the search box enter *+view +food +beach* this will search on all three keywords - -* Click on the blue *Search* button. You will get documents from only collection landmark and due to the options you selected you will see highlighted words in your results. -+ -image::fts-index-dynamic-search.png[,,align=left] - -* Verify you have some results -+ -image::fts-index-dynamic-search-results.png[,,align=left] - -include::partial$fts-adv-index-settings-and-other-features-in-the-ui.adoc[] diff --git a/modules/fts/pages/fts-creating-index-from-UI-classic-editor-geopoint.adoc b/modules/fts/pages/fts-creating-index-from-UI-classic-editor-geopoint.adoc deleted file mode 100644 index 4775fbef89..0000000000 --- a/modules/fts/pages/fts-creating-index-from-UI-classic-editor-geopoint.adoc +++ /dev/null @@ -1,81 +0,0 @@ -= Classic Editor - -[abstract] - -The classic editor is the most advanced tool where users can directly configure the index mapping with all capabilities. - -You can build the exact same index via the command line use the REST API, refer to xref:fts-creating-index-from-REST-geopoint.adoc[Creating a Geopoint Index via the REST API]. - -This section introduces index creations via a step by step walk through using the classic editor. The reader should be already familiar with the basic concepts of full-text search - -This example xref:fts-creating-index-from-UI-classic-editor-geopoint.adoc#main[Creating a Geopoint Index] covers simple geospatial Search indexes of type geopoint. -However it should be noted that it only scratches the surface and does not cover all geospatial features. - - -[#main] - -= Creating a Geopoint Index - -This section describes creating and Index on a bucket's collection across *all fields in the a collection*. In addition a specific field is overridden as a geospatial type of geopoint. - -This is equivalent to the xref:fts-creating-index-from-UI-classic-editor-legacy.adoc#main[Creating a Legacy Index] example with two exceptions: - - * The index is defined using the newer collections paradigm (instead of the "legacy" default mapping). - - * The field *geo* is overridden from the dynamic indexing to support geospatial queries as a type *geopoint*. - -To create the desired index through the Classic Editor: - -* Access the *Couchbase Web Console* > *Search* page. -+ -image::fts-search-page.png[,,align=left] - -include::partial$fts-creating-geopoint-common.adoc[] - -== Test the Geopoint Index with a simple query - -In the *Couchbase Web Console* > *Search* page. - -* Click on the index you just created (named "test_geopoint") to expand the Index's controls. - -* In the text area of the search box enter the following text (this is a radius query): -+ -[source, json] ----- -{ - "from": 0, - "size": 10, - "query": { - "location": { - "lon": -2.235143, - "lat": 53.482358 - }, - "distance": "100mi", - "field": "geo" - }, - "sort": [ - { - "by": "geo_distance", - "field": "geo", - "unit": "mi", - "location": { - "lon": -2.235143, - "lat": 53.482358 - } - } - ] -} ----- -+ -The above query-body specifies a longitude of `-2.235143` and a latitude of `53.482358`. -The target-field `geo` is specified, as is a `distance` of `100` miles: this is the radius within which target-locations must reside for their documents to be returned. Don't worry about newlines when you paste the text. - -* Click on the blue *Search* button. You will get documents from only collection landmark and due to the options you selected you will see highlighted words in your results. -+ -image::fts-index-geopoint-search.png[,,align=left] - -* Verify you have some results -+ -image::fts-index-geopoint-search-results.png[,,align=left] - -include::partial$fts-adv-index-settings-and-other-features-in-the-ui.adoc[] diff --git a/modules/fts/pages/fts-creating-index-from-UI-classic-editor-legacy.adoc b/modules/fts/pages/fts-creating-index-from-UI-classic-editor-legacy.adoc deleted file mode 100644 index 99961a3924..0000000000 --- a/modules/fts/pages/fts-creating-index-from-UI-classic-editor-legacy.adoc +++ /dev/null @@ -1,72 +0,0 @@ -= Classic Editor - -[abstract] - -The classic editor is the most advanced tool where users can directly configure the index mapping with all capabilities. - -You can build the exact same index via the command line use the REST API, refer to xref:fts-creating-index-from-REST-legacy.adoc[Creating a Legacy Index via the REST API]. - -This section introduces index creations via a step by step walk through using the classic editor. The reader should be already familiar with the basic concepts of full-text search - -This example xref:fts-creating-index-from-UI-classic-editor-legacy.adoc#main[Creating a Legacy Index] provides a simple introduction to using Search, however it is not optimized nor does it expose many useful features that the Search service supports. -This example only runs on the _default scope/collection (created when migrating bucket data into collections) and should be considered a legacy mode. This example is compatible with the pre collections bucket based paridigm. - -_Note a legacy index can only work on just one keyspace ._default._default._ - -[#main] - -= Creating a Legacy Index - -This section describes creating an Index on a bucket's *_default* scope/collection. This collection is created when upgrading from Buckets to Collections. - -To create a basic Search index on the _default collection, through the Classic Editor: - -* Access the *Couchbase Web Console* > *Search* page. -+ -image::fts-search-page.png[,,align=left] - -* Click the *Add Index* link in the upper right of the *Couchbase Web Console* > *Search* page. -+ -image::fts-add-initial.png[,600,align=left] - -* To define any index on which Full Text Search a unique name for the index in the *Index Name* field, on the upper-left. Note that only alphanumeric characters, hyphens, and underscores are allowed for index names and the first character of the name must be alphabetic. -+ -Enter *travel-sample-index* as the name of the Search index you are creating in the *Index Name* text-box. -+ -image::fts-index-name-default.png[,450,align=left] - -* Select the bucket *travel-sample* from the *Bucket* pull-down menu. -+ -Use the pull-down menu provided for the Bucket field, on the upper-right, and select a bucket that you are allowed to access to via the cluster's RBAC settings. -+ -image::fts-index-name-and-bucket-default.png[,450,align=left] - -* Save your index, left-click on the *Create Index* button near the bottom of the screen. -+ -This is all you need to specify in order to create a basic index for test and development. No further configuration is required. -+ -image::fts-index-create-button.png[,450,align=left] - -* If you subsequently Edit your Index it should look like the following: -+ -image::fts-edit-index-default.png[,600,align=left] - -== Test the Legacy Index with a simple query - -In the *Couchbase Web Console* > *Search* page. - -* Click on the index you just created (named "landmark-content-index") to expand the Index's controls. - -* In the text area of the search box enter *+view +food +beach* this will search on all three keywords - -* Click on the blue *Search* button. You will get documents from both type hotel and type landmark -+ -image::fts-index-default-search.png[,,align=left] - -* Verify you have some results -+ -image::fts-index-default-search-results.png[,,align=left] - -NOTE: Creating default indexes as above indexes across all fields is not recommended for production environments since it creates indexes that may be unnecessarily large, and therefore insufficiently performant. - -include::partial$fts-adv-index-settings-and-other-features-in-the-ui.adoc[] diff --git a/modules/fts/pages/fts-creating-index-from-UI-classic-editor-onefield.adoc b/modules/fts/pages/fts-creating-index-from-UI-classic-editor-onefield.adoc deleted file mode 100644 index b03981e722..0000000000 --- a/modules/fts/pages/fts-creating-index-from-UI-classic-editor-onefield.adoc +++ /dev/null @@ -1,126 +0,0 @@ -= Classic Editor - -[abstract] - -The classic editor is the most advanced tool where users can directly configure the index mapping with all capabilities. - -You can build the exact same index via the command line use the REST API, refer to xref:fts-creating-index-from-REST-onefield.adoc[Creating a One Field Index via the REST API]. - -This section introduces index creations via a step by step walk through using the classic editor. The reader should be already familiar with the basic concepts of full-text search - -This example xref:fts-creating-index-from-UI-classic-editor-onefield.adoc#main[Creating a One Field Index] starts to introduce advanced feature for optimizing and using a focused Search index. -However it should be noted that it only scratches the surface and does not cover: adding multiple collections under a scope; adding multiple field or fields from sub-objects; alternative analyzers, and geospatial features. - -[#main] - -= Creating a One Field Index via the UI - -This section describes creating and Index on a bucket's collection on just one field created on a non-default scope/collection. - -To create an one field Search index on the bucket: travel-sample, scope: inventory, collection: landmark, and field: content, through the Classic Editor: - -* Access the *Couchbase Web Console* > *Search* page. -+ -image::fts-search-page.png[,,align=left] - -* Click the *Add Index* link in the upper right of the *Couchbase Web Console* > *Search* page. -+ -image::fts-add-initial.png[,600,align=left] - -* To define any index on which Full Text Search a unique name for the index in the *Index Name* field, on the upper-left. Note that only alphanumeric characters, hyphens, and underscores are allowed for index names and the first character of the name must be alphabetic. -+ -Enter *landmark-content-index* as the name of the Search index you are creating in the *Index Name* text-box. -+ -image::fts-index-name-nondefault.png[,450,align=left] - -* Select the bucket *travel-sample* from the *Bucket* pull-down menu. -+ -Use the pull-down menu provided for the Bucket field, on the upper-right, and select a bucket that you are allowed to access to via the cluster's RBAC settings. -+ -image::fts-index-name-and-bucket-nondefault.png[,450,align=left] - -* Select the checkbox *[X] Use non-default scope/collections* -+ -This allows your index to stream mutations from one or more non-default collections under the selected bucket and scope. -+ -image::fts-select-nondefault-scope-collections.png[,450,align=left] - -* Use the newly visible pull-down menu provided for the *Scope* field, under the *[X] Use non-default scope/collections* checkbox, and select a bucket that you are allowed to access to via the cluster's RBAC settings. -+ -For this example select *inventory* which has multiple collections under it. -+ -image::fts-select-scope-nondefault.png[,450,align=left] - -* Under *Type Mapings*, unselect the checkbox *[ ] default | dynamic* - this will get rid of the warning in the prior step. -+ -This is required as this type mapping (the default mapping) is only valid for the ._default._default which is typically used to upgrade a 6.X server from a bucket into a more powerful collections paradigm. -+ -image::fts-uncheck-default-mapping.png[,600,align=left] - -* Click on the button *+ Add Type Mapping* - -** A new section with a *Collection* pull-down, *Analyzer* pull-down and a *[ ] only index specified fields* checkbox will appear. -+ -image::fts-index-menu1-nondefault-empty.png[,600,align=left] - -** Select *landmark* from the *Collection* pull-down, note the pull down will change to a text field prefilled with *inventory.landmark* - -** Check the *[X] only index specified fields* checkbox. -+ -image::fts-index-menu1-nondefault-filled.png[,600,align=left] - -** Click on the blue *ok* at the right of the section to save this mapping. - -** Hover over your newly created/saved row - -** Click on the blue *+* button the right side of the row. -+ -image::fts-index-menu1-nondefault-hover.png[,600,align=left] - -** A context menu of "insert child mapping" (for sub-objects) and "insert child field" (for properties) will appear. -+ -image::fts-index-menu2-nondefault-select.png[,600,align=left] - -** Select *insert child field* - -** another row menu will appear with the following controls: "field", "type", "text", "searchable as", "analyzer" "inherit", "index", "store", "include in _all field", "include term vectors", and "docvalues". -+ -image::fts-index-menu2-nondefault-empty.png[,600,align=left] - -** Set the text box *field* to *content*, this will also update "searchable as" to *content*. - -** Check *[X]* all the boxes "store", "include in _all field", "include term vectors", and "docvalues" - -** Click on the blue *ok* at the right of the section to save this sub-form. -+ -image::fts-index-menu2-nondefault-filled.png[,600,align=left] - -* Save your index, left-click on the *Create Index* button near the bottom of the screen. -+ -This is all you need to specify in order to create a more advanced index for test and development. No further configuration is required. -+ -image::fts-index-create-button.png[,450,align=left] - -* If you subsequently Edit your Index it should look like the following: -+ -image::fts-edit-index-nondefault.png[,600,align=left] - -NOTE: This index is an example of a potentially optimal index for use in a production environments since it creates only on index on a needed field as such it will be more performant that the first example. - -== Test the One Field Index with a simple query - -In the *Couchbase Web Console* > *Search* page. - -* Click on the index you just created (named "landmark-content-index") to expand the Index's controls. - -* In the text area of the search box enter *+view +food +beach* this will search on all three keywords - -* Click on the blue *Search* button. You will get documents from only collection landmark and due to the options you selected you will see highlighted words in your results. -+ -image::fts-index-nondefault-search.png[,,align=left] - -* Verify you have some results -+ -image::fts-index-nondefault-search-results.png[,,align=left] - -include::partial$fts-adv-index-settings-and-other-features-in-the-ui.adoc[] diff --git a/modules/fts/pages/fts-creating-index-from-UI-classic-editor.adoc b/modules/fts/pages/fts-creating-index-from-UI-classic-editor.adoc deleted file mode 100644 index 30cbe7debc..0000000000 --- a/modules/fts/pages/fts-creating-index-from-UI-classic-editor.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= Classic Editor Examples - -[abstract] - -The classic editor is the most advanced interface where users can directly configure the index mapping with all of capabilities in Search. - -include::partial$fts-user-prerequisites-common.adoc[] - -== Quickstart via the Classic Editor - -include::partial$fts-creating-indexes-common.adoc[] diff --git a/modules/fts/pages/fts-creating-index-from-UI-difference-between-classic-quick-editor.adoc b/modules/fts/pages/fts-creating-index-from-UI-difference-between-classic-quick-editor.adoc deleted file mode 100644 index 0efe7f30ec..0000000000 --- a/modules/fts/pages/fts-creating-index-from-UI-difference-between-classic-quick-editor.adoc +++ /dev/null @@ -1,40 +0,0 @@ -= Comparing the Classic Editor, Quick Editor, and the Search REST API - -To perform a Full Text Search, you can create indexes using one of the following methods: - -== Classic Editor - -To create an index, left-click on the *Add Index* button to invoke the Classic Editor. - -image::fts-add-index-initial.png[,600,align=left] - -== Quick Editor - -To quickly edit an index, left-click on the *Quick Edit* button towards the right-hand side on the Full Text Indexes panel to invoke the Quick Editor. - -image::fts-quick-edit-screen.png[,,align=left] - -== The Differences - -* The Classic Editor - -** Exposes the most advanced creation tool in which users directly configure the full range of index mapping options. - -** Intended for power users who are already familiar with the concepts of full-text search. - -* The Quick Editor - -** The Quick Editor allows users to configure the mapping by working with sample documents and higher-level abstractions. - -** The Quick Editor it does not support all of the advanced options of the Classic Editor. - -** The Quick Editor is intended for new users who are still learning about full-text search. - -* The Search REST API - -** Allows users to instantly configure indexes via JSON payloads. - -** Good for exporting, importing, and porting Search index definitions. - -** Complex syntax typically precludes editing outside of one of the UI editors. - diff --git a/modules/fts/pages/fts-creating-index-from-UI-quick-editor.adoc b/modules/fts/pages/fts-creating-index-from-UI-quick-editor.adoc deleted file mode 100644 index 23c501f8be..0000000000 --- a/modules/fts/pages/fts-creating-index-from-UI-quick-editor.adoc +++ /dev/null @@ -1,115 +0,0 @@ -= Quick Editor and Example - -[abstract] - -The Quick Editor allows a visual inerface select fields from collections to easily quickly build near optimal indexes. - -include::partial$fts-user-prerequisites-common.adoc[] - -== Creating a Search Index via the Quick editor - -Quick Editor is a newer interface in Search where you can quickly select the bucket, scope, and collection and choose the index fields from the searched documents. - -Due to this, the search query performance will be optimized as it has to handle fewer fields, increasing the query latency. - -To access the Full Text Search screen, left-click on the *Search* tab in the navigation bar on the left-hand side: - -image::fts-select-search-tab.png[,100,align=left] - -The Full Text Search screen now appears as follows: - -image::fts-search-page.png[,750,align=left] - -To quick edit an index, left-click on the *Quick Edit* button towards the right-hand side on the Full Text Indexes panel. - -The console contains areas for displaying indexes and aliases: but both are empty since none has yet been created. - -The Quick Edit screen appears: - -image::fts-quick-edit-screen.png[,800,align=left] - -Quick Edit allows you to modify and delete the configured mapped fields with the same index. To delete the mapped fields, select the field from the Mapped Fields grid and click Delete. - -To map the new fields, select the field from the JSON format document, change the configuration and click Add. - -image::fts-quick-edit-add-index.png[,750,align=left] - -To modify the mapped fields, select the field from the Mapped Fields, change the configuration and click Update. - -image::fts-quick-edit-update-index.png[,750,align=left] - -To save your changes in the quick index, left-click on the *Update Index* button near the bottom of the screen. - -== Quick Index - -To create a quick index, left-click on the *QUICK INDEX* button, towards the right-hand side: - -The QUICK INDEX screen appears: - -image::fts-quick-index-screen.png[,750,align=left] - -To define a basic index on which Full Text Search can be performed, begin by entering a unique name for the index into the Index Name field, on the upper-left: for example, travel-sample-index. (Note that only alphanumeric characters, hyphens, and underscores are allowed for index names. Note also that the first character of the name must be an alphabetic character.) Then, use the pull-down menu provided for the Keyspace field, at the upper-right, to specify as follows: - -bucket: `travel-sample` - -scope: `inventory` - -collection: `hotel` - -image::fts-quick-index-name-and-bucket.png[,750,align=left] - -The user can continue to randomly pick documents until they find a document of their intended type/schema. It is also possible to have multi-schema documents within a collection. - -image::fts-quick-index-json.png[,750,align=left] - -Select the required field from the document, which is needed to be mapped to this index. Once the field is selected, the configuration panel is displayed on the right. - -image::fts-quick-index-json-configuration.png[,750,align=left] - -Select the related type of the field from the *Type* dropdown. - -Select *Index this field as an identifier* to index the identifier values precisely without any transformation; for this case, language selection is disabled. - -After that, select the required language for the chosen field. - -Additionally, select from the following configuration options corresponding to the selected language: - -* *Include in search results*: Select this option to include the field in the search result. -* *Support highlighting*: Select this option to highlight the matched field. For this option, you must select the *Include in search result* option. -* *Support phrase matching*: Select this option to match the phrases in the index. -* *Support sorting and faceting*: Select this option to allow sorting and faceting the index. - -NOTE: Selecting configuration options requires additional storage and makes the index size larger. - -== Document Refresh/Reselection option - -The 'Refresh' option will randomly select a document from the given Keyspace (bucket.scope.collection). - -image::fts-quick-index-refresh.png[,750,align=left] - -Include In search results, Support phrase matching, and Support sorting and faceting. Searchable As field allows you to modify searchable input for the selected field. - -image::fts-quick-index-searchable-input.png[,400,align=left] - -Once the configuration is completed for the selected fields, click Add. Mapped fields will display the updated columns. - -image::fts-quick-index-json-mapping.png[,750,align=left] - -This is all you need to specify in order to create a basic index for test and development. No further configuration is required. - -Note, however, that such default indexing is not recommended for production environments since it creates indexes that may be unnecessarily large, and therefore insufficiently performant. To review the wide range of available options for creating indexes appropriate for production environments, see Creating Indexes. - -To save your index, - -Left-click on the *Create Index* button near the bottom of the screen: - - -At this point, you are returned to the Full Text Search screen. A row now appears, in the Full Text Indexes panel, for the quick index you have created. When left-clicked on, the row opens as follows: - -image::fts-new-quick-index-progress.png[,900,align=left] - -NOTE: The percentage figure appears under the indexing progress column, and is incremented in correspondence with the build-progress of the index. When 100% is reached, the index build is said to be complete. Search queries will, however, be allowed as soon as the index is created, meaning partial results can be expected until the index build is complete. - -Once the new index has been built, it supports Full Text Searches performed by all available means: the Console UI, the Couchbase REST API, and the Couchbase SDK. - -NOTE: If one or more of the nodes in the cluster running data service go down and/or are failed over, indexing progress may show a value > 100%. diff --git a/modules/fts/pages/fts-creating-index-with-rest-api.adoc b/modules/fts/pages/fts-creating-index-with-rest-api.adoc deleted file mode 100644 index 6df2deba10..0000000000 --- a/modules/fts/pages/fts-creating-index-with-rest-api.adoc +++ /dev/null @@ -1,106 +0,0 @@ -//[#index-creation-with-the-rest-api] -= Index Creation with REST API - -[abstract] - -The REST API can be used to instantly create indexes or query indexes from JSON payloads. - -include::partial$fts-user-prerequisites-common.adoc[] - -== Quickstart via the REST API - -include::partial$fts-creating-rest-indexes-common.adoc[] - -== REST API Index Creation Details - -The REST API can be used to create indexes. -Each call requires the following: - -* An appropriate username and password. -* Use of the verb `PUT`. -* An endpoint referring to the Full Text Search service, on port `8094`; and including the appropriate endpoint for index creation as defined by the xref:rest-api:rest-fts.adoc[Full Text Search REST API], including the name of the new index. -* Headers to specify settings for `cache-control` (`no-cache`) and `application-type` (`application/json`). -* A body containing the JSON document that defines the index to be created. -This must include the name of the bucket on which the index is to be created. - -The simplest way to create the appropriate JSON index-definition for the body is to create an index by means of the Couchbase Web Console, make a copy of the JSON index-definition produced (by accessing the xref:fts-creating-index-from-UI-classic-editor.adoc#using-the-index-definition-preview[Using the Index Definition Preview], explained above), modify the index-definition as appropriate, and finally, add the index-definition to the other, preceding elements required for the call. - -Note, however, that this requires modification of the `uuid` field; since the re-specifying of an existing field-value is interpreted as an attempted _update_, to an existing index. -Therefore, if the `uuid` field for an existing index appears in the Index Definition Preview as `"uuid": "3402702ff3c862c0"`, it should be edited to appear `"uuid": ""`. -A new ID will be allocated to the new index, and this ID will appear in the Index Definition Preview for the new index. - -Note also that a similar condition applies to the `sourceUUID` field, which refers to the targeted bucket: if a new index is being created for the same bucket that was referred to in the index-object copied from the UI, the field-value can remain the same. -However, if a different bucket is now to be targeted, the field should be edited to appear `"sourceUUID": ""` - -When specifying the endpoint for the index you are creating, make sure the path-element that concludes the endpoint is the same as that specified in the `name` field (which is the first field in the object). - -The following `curl` example demonstrates the creation of an index named `demoIndex`, on the `inventory` scope and `airline` collection, within the `travel-sample` bucket. -It assumes that Couchbase Server is running on `localhost`, and that the required username and password are `Administrator` and `password.` - -*Example* -[source,bourne] ----- -curl -XPUT -H "Content-Type: application/json" \ --u : http://localhost:8094/api/index/demoIndex -d \ -'{ - "type": "fulltext-index", - "name": "demoIndex", - "uuid": "4b70593a69cfcd79", - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "sourceUUID": "fc9b8eec20f8f7713ad14498064f50aa", - "planParams": { - "maxPartitionsPerPIndex": 1024, - "indexPartitions": 1 - }, - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "", - "mode": "scope.collection.type_field", - "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.airline": { - "dynamic": true, - "enabled": true - } - } - }, - "store": { - "indexType": "scorch", - "segmentVersion": 15 - } - }, - "sourceParams": {} -}' ----- - -If the call is successful, the following object is returned: - -[source,bourne] ----- -{"status":"ok"} ----- - -The newly created index can then be inspected in the Couchbase Web Console. - -== Index Update with REST API - -Specifying the "uuid" parameter in the index definition is required for the index creation to be treated as a valid update. - -NOTE: This uuid in the JSON body of a valid index update request has to match that of the existing index definition. Upon successful creation/update of an index, the uuid will be re-initialized. diff --git a/modules/fts/pages/fts-creating-indexes.adoc b/modules/fts/pages/fts-creating-indexes.adoc deleted file mode 100644 index 22da8c726d..0000000000 --- a/modules/fts/pages/fts-creating-indexes.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[#Creating-Indexes] -= Creating Search Indexes -:page-aliases: creating-indexes.adoc - -NOTE: Full Text Searches are supported by specially purposed indexes, which can be created either from the Couchbase Web Console, or by means of the REST API. - -The PUT request is the only way to create/update indexes. - -If the user does it from the UI/SDK - it will be translated to HTTP PUT requests and executed by curl. - -Specifying the "uuid" parameter in the index definition is required for the index introduction to be treated as a valid update. - -NOTE: This uuid has to match the one in the system already. -Upon a successful index creation/updation, the uuid of the index will be re-initialized. - -== Indexes and Full Text Search -Every Full Text Search is performed on a user-created Full Text Index, which contains the targets on which searches are to be performed. - -These targets are values derived from the textual and other contents of documents within a specified bucket or collections within a scope. - -Index-creation is highly configurable; you can select various attributes to search the specific information. - -For example, documents can be grouped by the user into different types (e.g. airline documents versus hotel documents), different scopes (e.g. inventory), and collections (e.g. airport or hotel). - -Based on the document-IDs, or the values of a designated document field, you can perform the following: - -* Assign index mapping to each document type - -* Assign analyzers to each index mapping - -* Apply the index mapping to a specific subset of document fields - -* Included or exclude the index mapping from the index - -Additionally, searches can be performed across multiple buckets/scopes, by means of index aliases or across multiple collections in a scope by selecting the respective non-default scope/collection(s) option. diff --git a/modules/fts/pages/fts-creating-with-curl-http-requests-json-structure.adoc b/modules/fts/pages/fts-creating-with-curl-http-requests-json-structure.adoc deleted file mode 100644 index 82bc46578d..0000000000 --- a/modules/fts/pages/fts-creating-with-curl-http-requests-json-structure.adoc +++ /dev/null @@ -1,80 +0,0 @@ -= Request Structure - -[abstract] -Full Text Index supports the JSON structure for the query request and the response. - -This topic explains the JSON fields use in the query. - -Json fields information of search request: - -.JSON fields in the query -[cols="2,2a"] -|=== -| Field | Description - -| Query -| The query specific details. - -| Size/Limit -| The number of results/hits requested related to pagination. - -| From/offset -| Related to pagination, this field indicates the starting point in the sorted result set (according to the score by default) from which the “size” amount of hits are taken to display. - -| Explain -| if set true, the response will include additional search score explanations. - -| Highlighting -| Allows setting the additional highlighting on the result set of matching terms. - -| Sort -| The order by which the result set is sorted. - -| Fields -| The fields value to be included in a hit in the result set. The fields should be indexed. - -Example: - -[source, JSON] ----- -curl -XPOST -H "Content-Type: application/json" -u username:password http://localhost:8094/api/index//query -d -'{ - "query": { - "query": "united" - }, - "collections":["airport"], - "fields":["airportname","country"] -}' ----- - -| Facets -| Aggregate information to be collected from the result set. - -Example: - -[source, JSON] ----- -"facets": { - "type": { - "size": 5, - "field": "type" - } -} ----- - -| Search_after -| Related to pagination, this field fetches the “size” number of results after the specified value in the sorted result set. - -| Search_before -| Related to pagination, this field fetches the “size” number of results before the specified value in the sorted result set. - -| score -| Related to pagination, this field fetches the “size” number of results after the specified value in the sorted result set. - -| collections -| Specifies the set of collections to which search would be limited. - -| IncludeLocations -| when set to true, this field returns the location of the occurrence of the search term in the document which has been hit. - -|=== \ No newline at end of file diff --git a/modules/fts/pages/fts-creating-with-curl-http-requests.adoc b/modules/fts/pages/fts-creating-with-curl-http-requests.adoc deleted file mode 100644 index 7a83ae1f4f..0000000000 --- a/modules/fts/pages/fts-creating-with-curl-http-requests.adoc +++ /dev/null @@ -1,2180 +0,0 @@ -= Queries with curl/http requests - -[abstract] -Couchbase Full Text Search supports running multiple types of queries through curl/http request. - -== Term Query - -The below sample responds with a list of documents in which the field _type_ contains the term *airline*. - -NOTE: The query works only for the terms with single word. - -=== Curl Request - -[source,JSON] ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d -'{ - "query": { - "term": "giverny", - "field": "title" - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "term":"giverny", - "field":"title" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_10064", - "score":10.033205341869529, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_10063", - "score":10.033205341869529, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":2, - "max_score":10.033205341869529, - "took":219177695, - "facets":null -} ----- - -== Phrase query - -The below sample responds with a list of documents in which the field _title_ contains specified phrase. For example, *Glossop* or *Giverny*. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d -'{ - "query": { - "terms": ["glencoe", "youth", "hostel"], - "field": "name" - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "terms":["glencoe","youth","hostel"], - "field":"name" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_10142", - "score":8.77552218572323, - "locations":{ - "name":{ - "glencoe":[ - { - "pos":1, - "start":0, - "end":7, - "array_positions":null - } - ], - "hostel":[ - { - "pos":3, - "start":14, - "end":20, - "array_positions":null - } - ], - "youth":[ - { - "pos":2, - "start":8, - "end":13, - "array_positions":null - } - ] - } - }, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":1, - "max_score":8.77552218572323, - "took":199844879, - "facets":null -} ----- - -== Match Query - -The below sample responds with a list of documents in which the field _name_ contains the exact matching term specified in the _term_ field. For example, "40-Mile Air". - -=== Curl Request - ----- - -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ -"query": { - "field": "name", - "match": "40-Mile Air" - } -}' - ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "match":"40-Mile Air", - "field":"name", - "prefix_length":0, - "fuzziness":0, - "operator":"or" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"airportDoc", - "score":10.30528795525373, - "sort":["_score"], - "fields":{"_$c":"airline"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_16687", - "score":1.085367329598051, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":2, - "max_score":10.30528795525373, - "took":86844745, - facets":null -} ----- - -== Match_Phrase query - -The below sample responds with a list of documents in which the field _name_ contains the exactly matching phrase specifed in _match_phrase_. For example, *40-Mile Air*. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "query": { - "match_phrase": "40-Mile Air", - "field": "name" - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "match_phrase": - "40-Mile Air", - "field":"name" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"airportDoc", - "score":10.305287955253732, - "locations":{ - "name":{ - "40":[ - { - "pos":1, - "start":0, - "end":2, - "array_positions":null - } - ], - "air":[ - { - "pos":3, - "start":8, - "end":11, - "array_positions":null - } - ], - "mile":[ - { - "pos":2, - "start":3, - "end":7, - "array_positions":null - } - ] - } - }, - "sort":["_score"], - "fields":{"_$c":"airline"} - } - ], - "total_hits":1, - "max_score":10.305287955253732, - "took":62498613, - "facets":null -} ----- - -== Fuzzy Query - -The below sample responds with a list of documents in which the field _name_ contains the term that matches with the phrase specified in the _match_ field. For example, *40-Mile Air*. It considers the matching to a degree specified in the _fuzziness_ field instead of exact matching. - -=== Curl Request - ----- - -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "query": { - "field": "name", - "match": "40-Mile Air", - "fuzziness": 2 - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "match":"40-Mile Air", - "field":"name", - "prefix_length":0, - "fuzziness":2, - "operator":"or" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_19199","score":0.17049220881184127, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"airportDoc", - "score":0.0956994969941305, - "sort":["_score"], - "fields":{"_$c":"airline"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21608", - "score":0.05690871682349641, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_19326", - "score":0.05579005002540549, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21037", - "score":0.05061580360832486, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_35854", - "score":0.04431672583269436, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_3491", - "score":0.04321478718467854, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_20421", - "score":0.04286437075446538, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_1362", - "score":0.037911531284201695, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21721", - "score":0.037911531284201695, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":163, - "max_score":0.17049220881184127, - "took":21410046, - "facets":null - } - ----- - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "query": { - "field": "name", - "match": "40-Mile Air", - "fuzziness": 1 - }, - "includeLocations": true -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "match":"40-Mile Air", - "field":"name", - "prefix_length":0, - "fuzziness":0, - "operator":"or" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"airportDoc", - "score":10.30528795525373, - "sort":["_score"], - "fields":{"_$c":"airline"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_16687", - "score":1.085367329598051, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":2, - "max_score":10.30528795525373, - "took":86844745, - "facets":null -} ----- - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "query": { - "field": "name", - "match": "40-Mile Air", - "fuzziness": 2 - }, - "includeLocations": true, "analyzer": "standard" -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "match":"40-Mile Air", - "field":"name", - "prefix_length":0, - "fuzziness":2, - "operator":"or" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":true, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_19199", - "score":0.17049220881184127, - "locations":{ - "name":{ - "aire":[ - { - "pos":1, - "start":0, - "end":4, - "array_positions":null - }, - { - "pos":5, - "start":26, - "end":30, - "array_positions":null - } - ], - "le":[ - { - "pos":3, - "start":15, - "end":17, - "array_positions":null - } - ] - } - }, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"airportDoc", - "score":0.0956994969941305, - "locations":{ - "name":{ - "40":[ - { - "pos":1, - "start":0, - "end":2, - "array_positions":null - } - ], - "air":[ - { - "pos":3, - "start":8, - "end":11, - "array_positions":null - } - ], - "mile":[ - { - "pos":2, - "start":3, - "end":7, - "array_positions":null - } - ] - } - }, - "sort":["_score"], - "fields":{"_$c":"airline"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21608", - "score":0.05690871682349641, - "locations":{ - "name":{ - "le":[ - { - "pos":2, - "start":6, - "end":8, - "array_positions":null - } - ], - "m":[ - { - "pos":3, - "start":9, - "end":10, - "array_positions":null - } - ] - } - }, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_20421", - "score":0.04286437075446538, - "locations":{ - "name":{ - "nh":[ - { - "pos":1, - "start":0, - "end":2, - "array_positions":null - } - ], - "nice":[ - { - "pos":2, - "start":3, - "end":7, - "array_positions":null - } - ] - } - }, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_1362", - "score":0.037911531284201695, - "locations":{ - "name":{ - "au":[ - { - "pos":1, - "start":0, - "end":2, - "array_positions":null - } - ] - } - }, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21721", - "score":0.037911531284201695, - "locations":{ - "name":{ - "iv":[ - { - "pos":3, - "start":12, - "end":14, - "array_positions":null - } - ] - } - }, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":163, - "max_score":0.17049220881184127, - "took":610500365, - "facets":null -} ----- - -== Prefix Query - -The below sample responds with a list of documents in which the _name_ field contains the text that starts with the given prefix. For example, *Air*. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "fields" : ["name"], - "query": { - "field": "name", - "prefix": "glasgow" - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "prefix":"glasgow", - "field":"name" - }, - "size":10, - "from":0, - "highlight":null, - "fields":["name"], - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_10138", - "score":6.026769086106564, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":1, - "max_score":6.026769086106564, - "took":181596318, - "facets":null -} - ----- - -== Regex Query - -The below sample responds with a list of documents in which the _name_ field contains the text in the given form of a regular expression. For example, _airport_. - - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ -"query":{ - "field":"name","regexp":"a[h-i]r[o-p]+ort"} - }' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "regexp":"a[h-i]r[o-p]+ort", - "field":"name"}, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_15913", - "score":5.0166026709347635, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_37887", - "score":4.486985781600578, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":2, - "max_score":5.0166026709347635, - "took":64912635, - "facets":null -} ----- - -== Wildcard Query - -The below sample responds with a list of documents in which the _country_ field contains the name that starts with *f* and ends with *ce*. For example, _france_. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "size":10, - "from":10, - "ctl":{"timeout":30}, - "query":{ - "wildcard":"f*ce", - "field":"country" - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "wildcard":"f*ce", - "field":"country" - }, - "size":10, - "from":10, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21850", - "score":6.175990572936377, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21872", - "score":6.175990572936377, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_24536", - "score":6.175990572936377, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21837", - "score":6.175990572936377, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21725", - "score":6.175990572936377, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21846", - "score":6.175990572936377, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_40662", - "score":6.175990572936377, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_35857", - "score":6.175990572936377, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21855", - "score":6.175990572936377, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_21669","score":6.175990572936377, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":141, - "max_score":6.175990572936377, - "took":49997068, - "facets":null -} ----- - -== Query String Query - -The below sample responds with a list of documents in which the _name_ field contains the text that starts with *air* and the _country_ field contains the name _france_. - - -=== Curl Request - -The *name* field prefixed with _air_ and the *country* field contains _france_. - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ -"query": {"query": "+name:air* +country:france"}}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "query":"+name:air* +country:france" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_19199", - "score":3.166810600229102, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":1, - "max_score":3.166810600229102, - "took":593704, - "facets":null -} - ----- - -=== Curl Request - -The below sample responds with a list of documents in which the *name* field is prefixed with _air_, and the *country* field contains anything other than _france_. - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ -"query": {"query": "+name:air* -country:france"}}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "query":"+name:air* -country:france" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"airportDoc", - "score":1.0997886699799067, - "sort":["_score"], - "fields":{"_$c":"airline"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_16687", - "score":1.0997886699799067, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_15913", - "score":0.9524449440916017, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_37887", - "score":0.8518926457255296, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":4, - "max_score":1.0997886699799067, - "took":537291, - "facets":null -} - ----- - -== Boosting the score - -The below sample responds with a list of documents in which both the _type_ field and _name_ field contains the term *airport* but the relevancy of the specified term, for example, _airport_ is more in the _name_ field than the _type_ field. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ -"query": { - "disjuncts":[ - { - "field":"city", - "match": "glossop", - "boost":5 - }, - { - "field":"title", - "match":"glossop" - } - ] -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "disjuncts":[ - { - "match":"glossop", - "field":"city", - "boost":5, - "prefix_length":0, - "fuzziness":0, - "operator":"or" - }, - { - "match":"glossop", - "field":"title", - "prefix_length":0, - "fuzziness":0, - "operator":"or" - } - ], - "min":0 - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_10161", - "score":11.390925020776914, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_10158", - "score":11.390925020776914, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_10160", - "score":11.390925020776914, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_10159", - "score":0.9131614588308529, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":4, - "max_score":11.390925020776914, - "took":339907764, - "facets":null -} ----- - -== Conjuncts and Disjuncts - -The below sample responds with a list of documents in which the _name_ field contains the text that starts with air and the _testing_ field is not *false*, and the _country_ field does not contain *france*. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "query": { - "conjuncts": [ - { - "query": "+name:air*" - }, - { - "disjuncts": [ - {"query": "+testing:false"}, - {"query": "country:france"} - ] - } - ] - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "conjuncts":[ - { - "query":"+name:air*" - }, - { - "disjuncts":[ - { - "query":"+testing:false" - }, - { - "query":"country:france" - } - ], - "min":0 - } - ] - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_19199", - "score":1.8423829850895888, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":1, - "max_score":1.8423829850895888, - "took":81919182, - "facets":null -} - ----- - -== Boolean Query - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "query" : { - "must": { - "conjuncts":[{"field":"type", "match": "hotel"}, {"field":"country", "match": "france"}] - }, - "must_not": { - "disjuncts": [{"field":"country", "match": "united states"}] - }, - "should": { - "disjuncts": [{"field":"free_parking", "bool": true}] - } - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "must":{ - "conjuncts":[ - { - "match":"hotel", - "field":"type", - "prefix_length":0, - "fuzziness":0, - "operator":"or" - }, - { - "match":"france", - "field":"country", - "prefix_length":0, - "fuzziness":0, - "operator":"or" - } - ] - }, - "should":{ - "disjuncts":[ - { - "bool":true, - "field":"free_parking" - } - ], - "min":0 - }, - "must_not":{ - "disjuncts":[ - { - "match":"united states", - "field":"country", - "prefix_length":0, - "fuzziness":0, - "operator":"or" - } - ], - "min":0 - } - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_21720", - "score":9.381573976364228, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_21849", - "score":9.381573976364228, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_20419", - "score":9.381573976364228, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_21725", - "score":9.381573976364228, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_20422", - "score":9.381573976364228, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_21852", - "score":9.381573976364228, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_21657", - "score":9.381573976364228, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_21838", - "score":9.381573976364228, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_21723", - "score":9.381573976364228, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_1359", - "score":9.381573976364228, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":140, - "max_score":9.381573976364228, - "took":116599230, - "facets":null -} - ----- - -== Date Range Query - -NOTE: This example needs an index created on beer-sample bucket. - -The below sample responds with a list of documents in which the _updateOn_ field contains the date in between the _start_ date and _end_ date, both inclusive. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index//query -d '{ - "query": { - "start": "2001-01-01","inclusive_start": true,"end": "2021-08-11","inclusive_end": true,"field": "updated" - } -}' ----- - -=== Curl Response - ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "start": "2001-01-01T00:00:00Z", - "end": "2021-08-11T00:00:00Z", - "inclusive_start": true, - "inclusive_end": true, - "field": "updated" - }, - "size": 10, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": ["-_score"], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "bix_3a91439dbf1df8ee_4c1c5584", - "id": "devil_s_canyon", - "score": 0.716641821033877, - "sort": ["_score"] - }, - { - "index": "bix_3a91439dbf1df8ee_4c1c5584", - "id": "abita_brewing_company-strawberry", - "score": 0.716641821033877, - "sort": ["_score"] - }, - ... - { - "index": "bix_3a91439dbf1df8ee_4c1c5584", - "id": "cains-2008_culture_beer", - "score": 0.716641821033877, - "sort": ["_score"] - }, - { - "index": "bix_3a91439dbf1df8ee_4c1c5584", - "id": "element_brewing_company-dark_element", - "score": 0.716641821033877, - "sort": ["_score"] - } - ], - "total_hits": 7303, - "max_score": 0.716641821033877, - "took": 1447295, - "facets": null -} ----- - -== Numeric Range Query - -The below sample responds with a list of documents in which the _id_ field is between the specified maximum (_max_) and minimum (_min_) values. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "query":{ - "field":"id", - "max": 8100, - "min": 8080 - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "min":10025, - "max":10030, - "field":"id" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_10025", - "score":0.922656832718857, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"hotel_10026", - "score":0.922656832718857, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":2, - "max_score":0.922656832718857, - "took":62274941, - "facets":null -} - ----- - -== DOC_ID QUERY - -The below sample responds with a list of documents in which the document ID is any of the specified ids. For example, airline_10 and airline_10123. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "query":{ - "ids":["airline_10", "airline_10123"] - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "ids":["airline_10","airline_10123"] - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"airline_10", - "score":1, - "sort":["_score"], - "fields":{"_$c":"airline"} - }, - { - "index":"DemoIndex_580e3ee6ba3ac900_4c1c5584", - "id":"airline_10123", - "score":1, - "sort":["_score"], - "fields":{"_$c":"airline"} - } - ], - "total_hits":2, - "max_score":1, - "took":139708973, - "facets":null -} - ----- - -== Bounded Rectangle Query - -The below sample responds with a list of documents in which the geolocation (_geo_) is bounded between the specified _top_left_ and _bottom_right_. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "query": { - "field": "geo", - "bottom_right": [-66.9326, 24.9493], - "top_left": [-125.0011, 49.5904] - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "top_left":[-125.0011,49.5904], - "bottom_right":[-66.9326,24.9493], - "field":"geo" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_23634", - "score":0.5583933812203372, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_17932", - "score":0.5583933812203372, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_25325", - "score":0.2575082889947619, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_25155", - "score":0.2575082889947619, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_25263", - "score":0.2575082889947619, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_3785", - "score":0.2575082889947619, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_25302", - "score":0.2575082889947619, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_25195", - "score":0.2575082889947619, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_25161", - "score":0.2575082889947619, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_76059e8b3887351c_4c1c5584", - "id":"hotel_25119", - "score":0.2575082889947619, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":361, - "max_score":0.5583933812203372, - "took":473390831, - "facets":null -} ----- - -== Point Distance Query - -The below sample responds with a list of documents in which the _location_ specified as geolocation is in the proximity of the distance specified in _distance_ field. A location is represented by means of longitude-latitude coordinate pairs. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "from": 0, - "size": 10, - "query": { - "location": { - "lon": -2.235143, - "lat": 53.482358 - }, - "distance": "1mi", - "field": "geo" - }, - "sort": [ - { - "by": "geo_distance", - "field": "geo", - "unit": "mi", - "location": { - "lon": -2.235143, - "lat": 53.482358 - } - } - ] - }' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "location":[-2.235143,53.482358], - "distance":"1mi", - "field":"geo" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":null, - "explain":false, - "sort":[ - { - "by":"geo_distance", - "field":"geo", - "location":{ - "lat":53.482358, - "lon":-2.235143 - }, - "unit":"mi" - } - ], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_17413", - "score":1.2317379157866246, - "sort":[" \u0001?U]S\\.e\u0002_"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_17414", - "score":1.2317379157866246, - "sort":[" \u0001?Z\u0000./\u0007Q\u0012\t"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_17415", - "score":1.2317379157866246, - "sort":[" \u0001?lg6,\u003c\u000cIL"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_17416", - "score":1.2317379157866246, - "sort":[" \u0001?r\u003cw\u0005GZ\u0005\u001f"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":4, - "max_score":1.2317379157866246, - "took":126456906, - "facets":null -} ----- - -== Date Range Facets Query - -NOTE: This example needs an index created on beer-sample bucket. - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index//query -d '{ - "query": { - "field": "style", - "term": "beer" - }, - "facets": { - "types": { - "size": 10, - "field": "updated", - "date_ranges": [ - { - "name": "old", - "end": "2011-01-01" - }, - { - "name": "new", - "start": "2011-01-02" - } - ] - } - } -}' ----- - -=== Curl Response - ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "term": "beer", - "field": "style" - }, - "size": 10, - "from": 0, - "highlight": null, - "fields": null, - "facets": { - "types": { - "size": 10, - "field": "updated", - "date_ranges": [ - { - "end": "2011-01-01", - "name": "old", - "start": "0001-01-01T00:00:00Z" - }, - { - "end": "0001-01-01T00:00:00Z", - "name": "new", - "start": "2011-01-02" - } - ] - } - }, - "explain": false, - "sort": [ - "-_score" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "bix_3a91439dbf1df8ee_4c1c5584", - "id": "erie_brewing_company-derailed_black_cherry_ale", - "score": 3.8396833650222075, - "sort": ["_score"] - }, - { - "index": "bix_3a91439dbf1df8ee_4c1c5584", - "id": "smuttynose_brewing_co-smuttynose_pumpkin_ale", - "score": 3.8396833650222075, - "sort": ["_score"] - }, - ... - { - "index": "bix_3a91439dbf1df8ee_4c1c5584", - "id": "warwick_valley_wine_co-doc_s_hard_apple_cider", - "score": 3.8396833650222075, - "sort": ["_score"] - } - ], - "total_hits": 86, - "max_score": 3.8396833650222075, - "took": 155002, - "facets": { - "types": { - "field": "updated", - "total": 86, - "missing": 0, - "other": 0, - "date_ranges": [ - { - "name": "old", - "end": "2011-01-01T00:00:00Z", - "count": 81 - }, - { - "name": "new", - "start": "2011-01-02T00:00:00Z", - "count": 5 - } - ] - } - } -} ----- - -== Numeric Range facet - -The below sample is to fetch the top 10 hotels based on the ratings given by the customers. - -* Type Mapping => type:hotel -* child-field: reviews.ratings.Service -* Analyzer: standard - -=== Curl Request - ----- -curl -XPOST -H "Content-Type: application/json" -u : http://localhost:8094/api/index/DemoIndex/query -d '{ - "query": { - "field": "reviews.content", - "term": "good" - }, - "facets": { - "types": { - "size": 10, - "field": "reviews.ratings.Service", - "numeric_ranges": [ - { - "name": "Awesome", - "min": 5 - }, - { - "name": "Good", - "max": 4 - }, - { - "name": "Avg", - "max": 3 - }, - { - "name": "Poor", - "max": 2 - }, - { - "name": "Bad", - "max": 1 - } - ] - } - } -}' ----- - -=== Curl Response - ----- -{ - "status":{ - "total":1, - "failed":0, - "successful":1 - }, - "request":{ - "query":{ - "term":"good", - "field":"reviews.content" - }, - "size":10, - "from":0, - "highlight":null, - "fields":null, - "facets":{ - "types":{ - "size":10, - "field":"reviews.ratings.Service", - "numeric_ranges":[ - { - "name":"Awesome", - "min":5 - }, - { - "name":"Good", - "max":4 - }, - { - "name":"Avg", - "max":3 - }, - { - "name":"Poor", - "max":2 - }, - {"name":"Bad", - "max":1 - } - ] - } - }, - "explain":false, - "sort":["-_score"], - "includeLocations":false, - "search_after":null, - "search_before":null - }, - "hits":[ - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_15134", - "score":1.608775098615459, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_3491", - "score":1.5929246603757872, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_9062", - "score":1.3135594084905977, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_25261", - "score":1.199110122199631, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_15976", - "score":1.0384598347067433, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_26142", - "score":1.029912757807367, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_3629", - "score":0.9683687809619517, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_5848", - "score":0.9479798384018671, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_16443", - "score":0.9479797868886458, - "sort":["_score"], - "fields":{"_$c":"hotel"} - }, - { - "index":"DemoIndex_41b91e3a4134783d_4c1c5584", - "id":"hotel_2814", - "score":0.9288267057398083, - "sort":["_score"], - "fields":{"_$c":"hotel"} - } - ], - "total_hits":656, - "max_score":1.608775098615459, - "took":343585473, - "facets":{ - "types": { - "field":"reviews.ratings.Service", - "total":1871, - "missing":3, - "other":0, - "numeric_ranges":[ - { - "name":"Good", - "max":4,"count":658 - }, - { - "name":"Awesome", - "min":5, - "count":579 - }, - { - "name":"Avg", - "max":3, - "count":366 - }, - { - "name":"Poor", - "max":2, - "count":219 - }, - { - "name":"Bad", - "max":1, - "count":49 - } - ] - } - } -} ----- \ No newline at end of file diff --git a/modules/fts/pages/fts-custom-filters.adoc b/modules/fts/pages/fts-custom-filters.adoc deleted file mode 100644 index 8bba8b666a..0000000000 --- a/modules/fts/pages/fts-custom-filters.adoc +++ /dev/null @@ -1,145 +0,0 @@ -= Custom Filters - -Custom filters can be viewed and modified from the index’s configuration page under the Index Settings section. Any custom filters that are configured for the current index can be viewed by expanding the Custom Filters panel. If no custom filters have been configured for the index, the Custom Filters panel will be empty. - -== Add Custom Filter - -To add a custom filter to a Full Text Index via the Couchbase Capella UI, the following permissions are required: - -You must have the `Project View` privileges for the project that contains the cluster. - -You must have a database user associated with your organization's user account. The database user must have Read/Write permissions for the bucket on which the index was created. - -The 'Custom Filters' panel shows no existing custom filters. - -The following four options are provided: - -=== Character Filter - -Adds a new character filter to the list of those available. -The new filter becomes available for inclusion in custom-created analyzers. - -Left-click the *+ Add Character Filter*. It displays the *Custom Character Filter* dialog: - -[#fts_custom_character_filter_dialog_initial] -image::fts-custom-character-filter-dialog-initial.png[,380,align=left] - -The following interactive fields are provided: - -* *Name*: A suitable, user-defined name for the new character filter. - -* *Type*: The type of filtering to be performed. Available options can be accessed from the pull-down menu to the right of the field. -(Currently, only `regexp` is available.) - -* *Regular Expression*: The specific _regular expression_ that the new character filter is to apply. Character-strings that match the expression will be affected; others will not. - -* *Replacement*: The replacement text that will be substituted for each character-string match returned by the regular expression. -If no replacement text is specified, the matched character-string will be omitted. - -The following completed fields define a character filter for deleting leading whitespace: - -[#fts_custom_character_filter_dialog_filled] -image::fts-custom-character-filter-dialog-filled.png[,380,align=left] - -When saved, the new character filter is displayed on its own row, with options for further editing and deleting: - -[#fts_custom_filters_panel_new_character_filter] -image::fts-custom-filters-panel-new-character-filter.png[,700,align=left] - -=== Tokenizer - -Adds a new tokenizer to the list of those available. - -The new tokenizer becomes available for inclusion in custom-created analyzers. - -Left-click the *+ Add Tokenizer*. It displays the *Custom Tokenizer* dialog: - -[#fts_custom_filters_tokenizer_dialog_initial] -image::fts-custom-filters-tokenizer-dialog-initial.png[,380,align=left] - -The following interactive fields are provided: - -* *Name*: A suitable, user-defined name for the new tokenizer. - -* *Type*: The process used in tokenizing. Available options can be accessed from the pull-down menu to the right of the field. -(Currently, `regexp` and `exception` are available.) - -* *Regular Expression*: The specific _regular expression_ used by the tokenizing process. - -The following completed fields define a tokenizer that removes uppercase characters: - -[#fts_custom_filters_tokenizer_dialog_completed] -image::fts-custom-filters-tokenizer-dialog-completed.png[,380,align=left] - -When saved, the new tokenizer is displayed on its own row, with options for further editing and deleting: - -[#fts_custom_filters_panel_new_tokenizer] -image::fts-custom-filters-panel-new-tokenizer.png[,700,align=left] - -=== Token filter - -Adds a new token filter to the list of those available. The new token filter becomes available for inclusion in custom-created analyzers. - -Left-click the *+ Add Token Filter*. It displays the *Custom Token Filter* dialog: - -[#fts_custom_filters_token_filter_dialog_initial] -image::fts-custom-filters-token-filter-dialog-initial.png[,380,align=left] - -The following interactive fields are provided: - -* *Name*: A suitable, user-defined name for the new token filter. - -* *Type*: The type of post-processing to be provided by the new token filter. The default is `length`, which creates tokens whose minimum number of characters is specified by the integer provided in the *Min* field and whose maximum by the integer provided in the *Max*. -Additional post-processing types can be selected from the pull-down menu at the right of the field: -+ -[#fts_custom_filters_token_filter_types] -image::fts-custom-filters-token-filter-types.png[,420,align=left] -+ -NOTE: The type-selection determines which interactive fields appear in the *Custom Token Filter* dialog, following *Name* and *Type*. -The pull-down menu displays a list of available types. -For descriptions, see the section xref:fts-analyzers.adoc#Token-Filters[Token Filters], on the page xref:fts-analyzers.adoc#Understanding-Analyzers[Understanding Analyzers]. - -* *Min*: The minimum length of the token, in characters. -Note that this interactive field is displayed for the `length` type, and may not appear, or be replaced, when other types are specified. -The default value is 3. - -* *Max*: The maximum length of the token, in characters. -Note that this interactive field is displayed for the `length` type and may not appear, or be replaced when other types are specified. -The default value is 255. - -The following completed fields define a token filter that restricts token-length to a minimum of 3, and a maximum of 255 characters: - -[#fts_custom_filters_token_filter_dialog_complete] -image::fts-custom-filters-token-filter-dialog-complete.png[,380,align=left] - -When saved, the new token filter is displayed on its own row, with options for further editing and deleting: - -[#fts_custom_filters_panel_new_token_filter] -image::fts-custom-filters-panel-new-token-filter.png[,700,align=left] - -=== Wordlist - -Adds a list of words to be removed from the current search. - -Left-click the *+ Add Word List*. It displays the *Custom Word List* dialog - -[#fts_custom_wordlist_dialog_initial] -image::fts-custom-wordlist-dialog-initial.png[,380,align=left] - -To create a custom word list, first, type a suitable name into the *Name* field. Then, add words by typing each individually into the field that bears the placeholder text, `word to be added`. - -After each word has been added, left-click on the [.ui]*+ Add* button, on the lower-right. The word is added to the central *Words* panel. - -Continue adding as many words as are required. - -For example: - -[#fts_custom_wordlist_dialog_complete] -image::fts-custom-wordlist-dialog-complete.png[,380,align=left] - -To remove a word, select the word within the *Words* panel and left-click on the *Remove* button. - -To save, left-click on [.ui]*Save*. The new word list is displayed on its own row, with options for further editing and deleting: - -[#fts_custom_filters_panel_new_word_list] -image::fts-custom-filters-panel-new-word-list.png[,700,align=left] \ No newline at end of file diff --git a/modules/fts/pages/fts-date-time-parsers.adoc b/modules/fts/pages/fts-date-time-parsers.adoc deleted file mode 100644 index 3553bd5904..0000000000 --- a/modules/fts/pages/fts-date-time-parsers.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= Date/Time Parsers - -Custom _date/time parsers_ can be specified to allow matches to be made across date/time formats. - -The Search Service expects dates to be in the format specified by RFC-3339 , which is a specific profile of ISO-8601. Since Search queries need to specify dates in RFC-3339 format, the dates that are stored in Full Text Indexes also need to be in RFC-3339 format. - -A date/time parser tells the Search Service ahead of time what the date/time layout of a field will be. If the Type of a child field is set to `datetime`, and the time layout(s) found in that field is not in RFC-3339 format, then you can specify a custom date/time parser that contains the layouts that the Search Service is to expect. - -To add a custom date/time parser to a Full Text Index via the Couchbase Capella UI, the following permissions are required: - -* You must have `Project View` privileges for the project that contains the cluster. - -* You must have a database user associated with your organization user account. The database user must have Read/Write permissions for the bucket on which the index was created. - -* Date/time parsers can be viewed and modified from the index’s configuration page, under the *Index Settings* section. -+ -Any date/time parsers that are configured for the current index can be viewed by expanding the *Date/Time Parsers* panel. If no date/time parsers have been configured for the index, the *Date/Time Parsers* panel will be empty. - -//[#fts_date_time_parser_initial] -//image::fts-date-time-parsers-empty.png[,300,align=left] - -== Add Date/Time Parsers - -_Date/Time Parsers_ can be specified to allow matches to be made across different formats: - -To add the date/time parser - -Left click the *+ Add Date/Time Parser* - -[#fts_date_time_parser_initial] -image::fts-date-time-parser-initial.png[,720,align=left] - -The *Customer Date/Time Parser* dialog appears. - -[#fts_custom_date_time_parser_dialog] -image::fts-custom-date-time-parser-dialog.png[,420,align=left] - -Enter a suitable name for the custom parser into the *Name* field. - -Left-click on the *+ Add* button to successively add the _layouts_ for the parser in the interactive field below the *Layouts* field, by after each one: - -This adds the layout to a list of layouts displayed in the *Layouts* field. - -To remove any of these, select its name in the *Layouts* field, and left-click on the *Remove* button. -When the list is complete, left-click on the *Save* button to save. - -Documentation on using the _Go Programming Language_ to specify _layouts_ is provided on the page http://golang.org/pkg/time/[Package time^]. -In particular, see the section http://golang.org/pkg/time/#Parse[func Parse^]. \ No newline at end of file diff --git a/modules/fts/pages/fts-default-settings.adoc b/modules/fts/pages/fts-default-settings.adoc deleted file mode 100644 index 3e89d7b33d..0000000000 --- a/modules/fts/pages/fts-default-settings.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= Default Settings - -Default settings can be specified in the *Advanced* panel. When opened, the Advanced panel appears as follows: - -[#fts_advanced_panel] -image::fts-advanced-panel.png[,420,align=left] - -The Advanced panel provides the following options: - -== Default Type - -The default type for documents in the selected bucket or scope and collection. The default value for this field is `default`. - -== Default Analyzer - -This is the default analyzer to be used. The default value is `standard`. - -The default analyzer is applicable to all the text fields across type mappings unless explicitly overridden. - -It is the _standard_ analyzer in which analysis is done by the means of the Unicode tokenizer, the to_lower token filter, and the stop token filter. - -== Default Date/Time Parser - -This is the default date/time parser to be used. - -The default datetime parser is applicable to all the datetime fields across the type mappings unless explicitly overridden. - -The default value is `dateTimeOptional`. - -== Default Field - -Indexed fields need to have this option selected to support `include in _all`, where _all is the composite field. - -The default value is `_all`. - -== Store Dynamic Fields - -This option, when selected, ensures the inclusion of field content in returned results. Otherwise, the field content is not included in the result. - -== Index Dynamic Fields - -This option, When selected, ensures that the dynamic fields are indexed. Otherwise, the dynamic fields are not indexed. - -== DocValues for Dynamic Fields - -This option, When selected, ensures that the values of the dynamic fields are included in the index. Otherwise, the dynamic field values are not included in the index. \ No newline at end of file diff --git a/modules/fts/pages/fts-index-analyzers.adoc b/modules/fts/pages/fts-index-analyzers.adoc deleted file mode 100644 index ca2a5cc843..0000000000 --- a/modules/fts/pages/fts-index-analyzers.adoc +++ /dev/null @@ -1,481 +0,0 @@ -[#Understanding-Analyzers] -= Understanding Analyzers -:page-aliases: using-analyzers.adoc,fts-analyzers.adoc,fts-using-analyzers.adoc - -[abstract] -Analyzers increase search-awareness by transforming input text into token-streams, which permit the management of richer and more finely controlled forms of text-matching. -An analyzer consists of modules, each of which performs a particular, sequenced role in the transformation. - -[#principles-of-text-analysis] -== Principles of Text-Analysis - -_Analyzers_ pre-process input-text submitted for Full Text Search; typically, by removing characters that might prohibit certain match-options. - -The analysis is performed on document-contents when indexes are created and is also performed on the input-text submitted for a search. -The benefit of analysis is often referred to as _language awareness_. - -For example, if the input-text for a search is `enjoyed staying here`, and the document-content contains the phrase `many enjoyable activities`, the dictionary-based words do not permit a match. -However, by using an analyzer that (by means of its inner _Token Filter_ component) _stems_ words, the input-text yields the tokens `enjoy`, `stay`, and `here`; while the document-content yields the tokens `enjoy` and `activ`. -By means of the common token `enjoy`, this permits a match between `enjoyed` and `enjoyable`. - -Since different analyzers pre-process text in different ways, effective Full Text Search depends on the right choice of the analyzer, for the type of matches that are desired. - -Couchbase Full Text Search provides a number of pre-constructed analyzers that can be used with Full Text Indexes. -Additionally, analyzers can be custom-created by means of the Couchbase Web Console. -The remainder of this page explains the architecture of analyzers and describes the modular components that Couchbase Full Text Search makes available for custom-creation. -It also lists the pre-constructed analyzers that are available and describes the modules that they contain. - -For examples of both selecting and custom-creating analyzers by means of the Couchbase Web Console. - -[#analyzer-architecture] -== Analyzer Architecture - -Analyzers are built from modular components: - -* *Character Filters* remove undesirable characters from input: for example, the `html` character filter removes HTML tags, and indexes HTML text-content alone. - -* *Tokenizers* split input-strings into individual _tokens_, which together are made into a _token stream_. -The nature of the decision-making whereby splits are made, differs across tokenizers. - -* *Token Filters* are chained together, with each performing additional post-processing on each token in the stream provided by the tokenizer. -This may include reducing tokens to the _stems_ of the dictionary-based words from which they were derived, removing any remaining punctuation from tokens, and removing certain tokens deemed unnecessary. - -Each component-type is described in more detail below. You can use these components to create custom analyzers from the Couchbase Web Console. - -NOTE: If you have configured an analyzer for your field, you cannot specify any other analyzer for the field in the search request. However, if you do not specify any analyzer in your search query, the query will automatically choose the analyzer that was used for indexing. - -[#Character-Filters] -=== Character Filters - -_Character Filters_ remove undesirable characters. - -The following filters are available: - -* *asciifolding*: Converts characters that are in the first 127 ASCII characters (`basic latin` unicode block) into their ASCII equivalents. - -* *html*: Removes html elements such as `

`. - -* *regexp*: Uses a regular expression to match characters that should be replaced with the specified replacement string. - -* *zero_width_spaces*: Substitutes a regular space-character for each _zero-width non-joiner_ space. - -[#Tokenizers] -=== Tokenizers - -Tokenizers split input-strings into individual tokens: characters likely to prohibit certain kinds of matching (for example, spaces or commas) are omitted. - -The tokens so created are then made into a _token stream_ for the query. - -The following tokenizers are available from the Couchbase Web Console: - -* *Hebrew*: Creates tokens by breaking input-text into subsets that consist of hebrew letters only: characters such as punctuation-marks and numbers are omitted. -+ -This does a restricted set of operations on the punctuations for example, it can’t combine the two geresh into a single gershayim (both of which are used as punctuations) - -* *Letter*: Creates tokens by breaking input-text into subsets that consist of letters only: characters such as punctuation-marks and numbers are omitted. -+ -The creation of a token ends whenever a non-letter character is encountered. -For example, the text `Reqmnt: 7-element phrase` would return the following tokens: `Reqmnt`, `element`, and `phrase`. - -* *Single*: Creates a single token from the entirety of the input-text. -For example, the text `in each place` would return the following token: `in each place`. -+ -NOTE: This may be useful for handling URLs or email addresses, which can thus be prevented from being broken at punctuation or special-character boundaries. -+ -It may also be used to prevent multi-word phrases (for example, place names such as `Milton Keynes` or `San Francisco`) from being broken up due to whitespace; so that they become indexed as a single term. - -* *Unicode*: Creates tokens by performing _Unicode Text Segmentation_ on word-boundaries, using the https://github.com/blevesearch/segment[segment^] library. -+ -For examples, see http://www.unicode.org/reports/tr29/#Word_Boundaries[Unicode Word Boundaries^]. - -* *Web*: It identifies email addresses, URLs, Twitter usernames and hashtags, and attempts to keep them intact, indexed as individual tokens. - -* *Whitespace*: Creates tokens by breaking input-text into subsets according to where whitespace occurs. -+ -For example, the text `in each place` would return the following tokens: `in`, `each`, and `place`. - -[#Token-Filters] -=== Token Filters - -_Token Filters_ accept a token-stream provided by a tokenizer and make modifications to the tokens in the stream. - -A frequently used form of token filtering is _stemming_; this reduces words to a base form that typically consists of the initial _stem_ of the word (for example, `play`, which is the stem of `player`, `playing`, `playable`, and more). - -With the stem used as the token, a wider variety of matches can be made (for example, the input-text `player` can be matched with the document-content `playable`). - -The following kinds of token-filtering are supported by Couchbase Full Text Search: - -* *apostrophe*: Removes all characters after an apostrophe and the apostrophe itself. For example, `they've` becomes `they`. - -* *camelCase*: Splits camelCase text to tokens. - -* *dict_compound*: Allows user-specification of a dictionary whose words can be combined into compound forms, and individually indexed. - -* *edge_ngram*: From each token, computes https://en.wikipedia.org/wiki/N-gram[n-grams^] that are rooted either at the front or the back. - -* *elision*: Identifies and removes characters that prefix a term and are separated from it by an apostrophe. -+ -For example, in French, `l'avion` becomes `avion`. - -* *mark_he*: Marks the hebrew, non-hebrew and numeric tokens in the tokenstream. - -* *niqqud_he*: Ensures that niqqudless spelling for the further hebrew analysis. - -* *lemmatizer_he*: Lemmatizes/gets similar forms of the hebrew words, and if necessary handles spelling mistakes to a certain extent using yud and vav as part of tolerance process. - -* *keyword_marker*: Identifies keywords and marks them as such. These keywords are then ignored by any downstream stemmer. - -* *length*: Removes tokens that are too short or too long for the stream. - -* *to_lower*: Converts all characters to lower case. - -* *ngram*: From each token, computes https://en.wikipedia.org/wiki/N-gram[n-grams^]. -+ -There are two parameters, which are the minimum and maximum n-gram length. - -* *reverse*: Simply reverses each token. - -* *shingle*: Computes multi-token shingles from the token stream. -+ -For example, the token stream `the quick brown fox`, when configured with a shingle minimum and a shingle maximum length of 2, produces the tokens `the quick`, `quick brown`, and `brown fox`. - -* *stemmer_porter*: Transforms the token stream as per the https://tartarus.org/martin/PorterStemmer/[porter stemming algorithm^]. - -* *stemmer_snowball*: Uses http://snowball.tartarus.org/[libstemmer^] to reduce tokens to word-stems. - -* *stop_tokens*: Removes from the stream tokens considered unnecessary for a Full Text Search. For example, `and`, `is`, and `the`. For example, `HTML` becomes `html`. - -* *truncate*: Truncates each token to a maximum-permissible token-length. - -* *normalize_unicode*: Converts tokens into http://unicode.org/reports/tr15/[Unicode Normalization Form^]. - -* *unique*: Only indexes unique tokens during analysis. - -NOTE: The token filters are frequently configured according to the special characteristics of individual languages. -Couchbase Full Text Search provides multiple language-specific versions of the *elision*, *normalize*, *stemmer*, *possessive*, and *stop* token filters. - -The following table lists the specially supported languages for token filters. - -.Supported Token-Filter Languages -[[token_filter_languages_5.5]] -[cols="1,4"] -|=== -| Name | Language - -| ar -| Arabic - -| bg -| Bulgarian - -| ca -| Catalan - -| cjk -| Chinese {vbar} Japanese {vbar} Korean - -| ckb -| Kurdish - -| da -| Danish - -| de -| German - -| el -| Greek - -| en -| English - -| es -| Spanish (Castilian) - -| eu -| Basque - -| fa -| Persian - -| fi -| Finnish - -| fr -| French - -| ga -| Gaelic - -| gl -| Spanish (Galician) - -| he -| Hebrew - -| hi -| Hindi - -| hu -| Hungarian - -| hr -| Croatian - -| hy -| Armenian - -| id, in -| Indonesian - -| it -| Italian - -| nl -| Dutch - -| no -| Norwegian - -| pt -| Portuguese - -| ro -| Romanian - -| ru -| Russian - -| sv -| Swedish - -| tr -| Turkish -|=== - -[#Creating-Analyzers] -== Creating Analyzers - -Analyzers increase search-awareness by transforming input text into token-streams, which permit the management of richer and more finely controlled forms of text-matching. - -An analyzer consists of modules, each of which performs a particular role in the transformation (for example, removing undesirable characters, transforming standard words into stemmed or otherwise modified forms, referred to as tokens, and performing miscellaneous post-processing activities). - -For more information on analyzers, see -xref:fts-analyzers.adoc[Understanding Analyzers]. - -A default selection of analyzers is made available from the pull-down menu provided by the *Type Mappings* interface discussed above. Additional analyzers can be custom-created, by means of the *Analyzers* panel, which appears as follows: - -To create a new analyzer, left-click on the *+ Add Analyzer* button. - -[#fts_analyzers_panel_initial] -image::fts-analyzers-panel-initial.png[,700,align=left] - -The *Custom Analyzer* dialog appears: - -[#fts_custom_analyzer_dialog_initial] -image::fts-custom-analyzer-dialog-initial.png[,500,align=left] - -The dialog contains four interactive panels. - -* *Name:* A suitable, user-defined name for the analyzer. - -* *Character Filters:* One or more available character filters. (These strip out undesirable characters from input: for example, the `html` character filter removes HTML tags, and indexes HTML text-content alone.) To select from the list of available character filters, use the pull-down menu: -+ -[#fts_analyzers_panel_select_char_filter] -image::fts-analyzers-panel-select-char-filter.png[,500,align=left] -+ -Following addition of one character filter, to add another, left-click on the *+ Add* button, to the right of the field. -+ -For an explanation of character filters, see the section in xref:#Character-Filters[Understanding Analyzers]. - -* *Tokenizer:* One of the available tokenizers. (These split input-strings into individual tokens, which together are made into a token stream. Typically, a token is established for each word.) The default value is `unicode`. To select from a list of all tokenizers available, use the pull-down menu: -+ -[#fts_add_tokenizer_pulldown] -image::fts-add-tokenizer-pulldown.png[,500,align=left] -+ -For more information on tokenizers, see the section in xref:#Tokenizers[Understanding Analyzers]. - -* *Token Filter:* One or more of the available token filters. (When specified, these are chained together, to perform additional post-processing on the token stream.) To select from the list of available filters, use the pull-down menu: -+ -[#fts_analyzers_panel_select_token_filter] -image::fts-analyzers-panel-select-token-filter.png[,500,align=left] -+ -Following addition of one token filter, to add another, left-click on the *+ Add* button, to the right of the field. -+ -For more information on token filters, see the section in xref:#Token-Filters[Understanding Analyzers]. - -When these fields have been appropriately completed, save by left-clicking on the *Save* button. On the *Edit Index* screen, the newly defined analyzer now appears in the *Analyzers* panel, with available options displayed for further editing, and deleting. For example: - -[#fts_analyzers_panel_subsequent] -image::fts-analyzers-panel-subsequent.png[,700,align=left] - -[#Pre-Constructed-Analyzers] -== Pre-Constructed Analyzers - -The user can select several pre-constructed analyzers available in the Couchbase Web Console. Refer to Creating Indexes for more examples of selection see xref:fts-creating-indexes.adoc[Creating Indexes]. - -The four basic pre-constructed analyzers are demonstrated below via an online tool https://bleveanalysis.couchbase.com/analysis: - -. *Keyword*: This analyzer creates a single token representing the entire input. It forces exact matches and preserves characters such as spaces. -+ -For example, the text “the QUICK brown fox jumps over the lazy Dog” phrase returns the following tokens: -+ -image::fts-pre-constructed-analysers-keyword.png[,700,align=left] - -. *Simple*: The simple analyzer uses the Letter tokenizer, which keeps letters only. The Letter tokenizer creates tokens by breaking input text into subsets consisting of only letters. It omits characters such as punctuation marks and numbers. It ends the token creation when it encounters a non-letter character. -+ -For example, the text “the QUICK brown fox jumps over the lazy Dog” phrase returns the following tokens: -+ -image::fts-pre-constructed-analysers-simple.png[,700,align=left] - -. *Standard*: The standard analyzer uses the Unicode tokenizer, the `to_lower` token filter, and the stop token filter for analysis. - -* *Unicode*: It creates tokens by performing Unicode Text Segmentation on word-boundaries, using the xref::https://github.com/blevesearch/segment[segment] library. -+ -Token Filters accept a token-stream provided by a tokenizer and modify the tokens in the stream. E.g, stop word filtering and lower casing. - -* *to_lower filter*: It converts all characters to the lower case. For example, HTML becomes html. - -* *stop_token filter*: It removes words such as ‘and’, ‘is’, and ‘the’. -+ -For example, the text “The QUICK Brown Fox Jumps Over The Lazy Dog” phrase returns the following tokens: -+ -image::fts-pre-constructed-analysers-standard.png[,700,align=left] -+ -NOTE: Analyzers - Reserve Words -The ‘standard’ analyzer removes stop words defined by the English language and special characters. If the user wants the stop words and special characters to be searchable, then the user will need to use a pre-constructed “simple” analyzer. - -. *Web*: The web analyzer identifies email addresses, URLs, Twitter usernames and hashtags, and attempts to keep them intact, indexed as individual tokens. -+ -For example, the web analyzer identifies the email address and keeps it intact, indexed as individual token. -+ -image::fts-pre-constructed-analysers-web.png[,750,align=left] - -[#Supported-Languages] -=== Support Analyzer Languages -The Search Service has pre-built analyzers for the following languages: - -[[analyzer_languages_5.5]] -[cols="1,4"] -|=== -| Name | Language - -| ar -| Arabic - -| cjk -| Chinese {vbar} Japanese {vbar} Korean - -| ckb -| Kurdish - -| da -| Danish - -| de -| German - -| en -| English - -| es -| Spanish (Castilian) - -| fa -| Persian - -| fi -| Finnish - -| fr -| French - -| he -| Hebrew - -| hi -| Hindi - -| hu -| Hungarian - -| hr -| Croatian - -| it -| Italian - -| nl -| Dutch - -| no -| Norwegian - -| pt -| Portuguese - -| ro -| Romanian - -| ru -| Russian - -| sv -| Swedish - -| tr -| Turkish -|=== - -== Analyzers - Search Functions - -xref:n1ql:n1ql-language-reference/searchfun.adoc[Search functions] allow users to execute full text search requests within a {sqlpp} query. - -In the context of {sqlpp} queries, a full text search index can be described as one of the following : - -* xref:n1ql:n1ql-language-reference/covering-indexes.adoc[Covering index] - -* Non-covering index - -This characterization depends on the extent to which it could answer all aspects of the SELECT predicate and the WHERE clauses of a {sqlpp} query. -A {sqlpp} query against a non-covering index will go through a "verification phase.” In this phase, documents are fetched from the query service based on the results of the search index, and the documents are validated as per the clauses defined in the query. - -For example, an index with only the field `field1` configured is considered a non-covering index for a query `field1=abc` and `field2=xyz`. - -== Use case - -Consider a use case where a user has defined a special analyzer for a field in their full text search index. The following can be expected: - -. If the query does not use the same analyzer as specified in the full text search index, the query will not be allowed to run. - -. By default, the analyzer used for indexing the field (as per the index definition) will be picked up if no analyzer is specified in the analytic query. - -. If the index is a non-covering index for an analytic query and the user has not specified an explicit analyzer to be used, the verification phase might drop documents that should have been returned as results due to lack of query context. - -The user can explicitly specify the search query context in the following three ways: - -. Explicitly specify the analyzer to use in the query (to match with that specified in the index). -+ -Example 1 -+ -.... -SEARCH(keyspace, {"match": "xyz", "field": "abc", "analyzer": "en"}) -.... - -. Specify index name within the options argument of the SEARCH function, so this index’s mapping is picked up during the verification process -+ -Example 2 -+ -.... -SEARCH(keyspace, {"match": "xyz", "field": "abc"}, {"index": "fts-index-1"}) -.... - -. Specify the index mapping itself as a JSON object within the options argument of the SEARCH function, which is used directly for the verification process -+ -Example 3 -+ -.... -SEARCH(keyspace, {"match": "xyz", "field": "abc"}, {"index": {.......}) -.... - -NOTE: If users fail to provide this query context for non-covering queries, they may see incorrect results, including dropped documents, especially while using non-standard and custom analyzers. diff --git a/modules/fts/pages/fts-index-partitions.adoc b/modules/fts/pages/fts-index-partitions.adoc deleted file mode 100644 index 82fb59249f..0000000000 --- a/modules/fts/pages/fts-index-partitions.adoc +++ /dev/null @@ -1,34 +0,0 @@ -= Index Partitioning - -_Index Partitioning_ increases query performance by dividing and spreading a large index of documents across multiple nodes. This feature is available only in Couchbase Server Enterprise Edition. - -The benefits include: - -* The ability to scale out horizontally as index size increases. - -* Transparency to queries, requiring no change to existing queries. - -* Reduction of query latency for large, aggregated queries; since partitions can be scanned in parallel. - -* Provision of a low-latency range query while allowing indexes to be scaled out as needed. - -== Index Partitions - -The *Index Partitions* interface provides a section to enter the number of partitions the index is to be split into: - -[#fts_index_partitions_interface] -image::fts-index-partitions-interface.png[,300,align=left] - -The default option for this setting is 1. Note that this number represents the number of active partitions for an index, and the active partitions are distributed across all the nodes in the cluster where the search service is running. - -NOTE: The type of index is saved in its JSON definition, which can be previewed in the _Index Definition Preview_ panel, at the right-hand side. - -See xref:fts-creating-index-from-UI-classic-editor.adoc#using-the-index-definition-preview[Using the Index Definition Preview]. - -[source,javascript] ----- -"planParams": { - "numReplicas": 0, - "indexPartitions": 6 -}, ----- \ No newline at end of file diff --git a/modules/fts/pages/fts-index-replicas.adoc b/modules/fts/pages/fts-index-replicas.adoc deleted file mode 100644 index 3578a73902..0000000000 --- a/modules/fts/pages/fts-index-replicas.adoc +++ /dev/null @@ -1,18 +0,0 @@ -= Index Replicas -:page-aliases: fts-search-response-index-partition.adoc - -Index Replicas support availability: if an Index Service-node is lost from the cluster, its indexes may exist as replicas on another cluster-node that runs the Index Service. - -If an active index is lost, a replica is promoted to active status, and use of the index is uninterrupted. - -The *Index Replicas* interface allows up to three index replicas to be selected, from a pull-down menu: - -[#fts_index_replicas_interface] -image::fts-index-replicas-interface.png[,250,align=left] - -Each replica partition exists on a node, separate from its active counterpart and from any other replica of that active partition. The user cannot add more than the permitted number of replicas by the current cluster configuration. If the user tries to add more replicas it will result in an error message. - -[#fts_index_replicas_error_message] -image::fts-index-replicas-error-message.png[,220,align=left] - -The above error implies that there are not enough search nodes in the cluster to support the configured number of replicas. diff --git a/modules/fts/pages/fts-index-type.adoc b/modules/fts/pages/fts-index-type.adoc deleted file mode 100644 index 8aec04d394..0000000000 --- a/modules/fts/pages/fts-index-type.adoc +++ /dev/null @@ -1,37 +0,0 @@ -= Index Type - -The *Index Type* interface provides a drop-down menu from which the appropriate index type can be selected: - -[#index_type_interface_image] -image::fts-index-type-interface.png[,300,align=left] - -Following options are available: - -* *Version 5.0 (Moss)* is the standard form of index to be used in test, development, and production. This version is deprecated. - -* *Version 6.0 (Scorch)* reduces the size of the index-footprint on disk and provides enhanced performance for indexing and mutation-handling - -NOTE: The type of an index is saved in its JSON definition, which can be previewed in the _Index Definition Preview panel_, at the right-hand side. - -== Example - -Version 5.0 contained the following value for the store attribute: - -[source,Javascript] ----- - -"store": { - "kvStoreName": "mossStore" -}, ----- - -Version 6.0 and later contains a different value: - -[source,javascript] ----- - -"store": { - "kvStoreName": "", - "indexType": "scorch" -}, ----- \ No newline at end of file diff --git a/modules/fts/pages/fts-introduction.adoc b/modules/fts/pages/fts-introduction.adoc deleted file mode 100644 index ebb1e8fa01..0000000000 --- a/modules/fts/pages/fts-introduction.adoc +++ /dev/null @@ -1,135 +0,0 @@ -= Introduction to Full Text Search -:page-aliases: full-text-intro.adoc - -[abstract] -_Full Text Search_ (FTS) lets you create, manage, and query _indexes_, defined on JSON documents within a Couchbase bucket. - -== Full Text Search - -Provided by the xref:learn:services-and-indexes/services/search-service.adoc[Search Service], full text search (FTS) enables the users to create, manage, and query multi-purposed indexes defined on JSON documents within a Couchbase bucket. - -In addition to exact matches, the full-text index can perform various search functions based on matching given terms/search parameters. - -Couchbase’s Global Secondary Indexes (GSI) can be used for range scans and regular pattern search, whereas FTS offers extensive capabilities for natural-language querying. - - -[#fundamentals-of-full-text-search] -== Full Text Search: Fundamentals - -Every Full Text Search is performed on a user-created _Full Text Index_, which contains the targets on which searches are to be performed: these targets are values derived from the textual and other contents of documents within a specified bucket. - -[#features-of-full-text-search] -== Features of Full Text Search - -_Full Text Search_ provides Google-like search capability on JSON documents. -Couchbase's Global Secondary Indexes (GSI) can be used for range scans and regular pattern search, whereas FTS provides extensive capabilities for natural-language querying. -The query below looks for documents with all of the strings ("paris", "notre", "dame"). - -=== Example - -[source,json] ----- -{ - "explain": false, - "fields": [ - "*" - ], - "highlight": {}, - "query": { - "query": "+paris +notre +dame" - } -} ----- - -This query returns the following result (shown partially) from the FTS index scan on the travel-sample sample bucket. -For each matched document, the hits field shows the document id, the score, the fields in which a matched string occurs, and the position of the matched string. - -[source,json] ----- -"hits": [ - { - "index": "trsample_623ab1fb8bfc1297_6ddbfb54", - "id": "landmark_21603", - "score": 2.1834097375254955, - "locations": { - "city": { - "paris": [ - { - "pos": 1, - "start": 0, - "end": 5, - "array_positions": null - } - ] - }, - "content": { - "dame": [ - { - "pos": 23, - "start": 169, - "end": 173, - "array_positions": null - }, -... -] ----- - -Examples of natural language support include: - -* _Language-aware_ searching; allowing users to search for, say, the word `traveling`, and additionally obtain results for `travel` and `traveler`. -* xref:fts-scoring.adoc[_Scoring_] of results, according to relevancy; allowing users to obtain result-sets that only contain documents awarded the highest scores. -This keeps result-sets manageably small, even when the total number of documents returned is extremely large. - -== Stages of Full text search query -A Full Text Search query , once built at the client, can be targeted to any server in the Couchbase cluster hosting the search service. - -Here are the stages it goes through: - -. The server that the client targets the search request to, assumes the role of the orchestrator or the coordinating node once it receives the external request. - -. The coordinating node first looks up the index (making sure it exists). - -. The coordinating node obtains the “plan” that the index was deployed with. The plan contains details on how many partitions the index was split into and all the servers’ information where any of these partitions reside. - -. The coordinating node sets up a unique list of servers that it needs to dispatch an “internal” request to. A server in the Couchbase cluster is eligible if and only if it hosts a partition belonging to the index under consideration. - -. Once the internal requests have been dispatched by the coordinating node to each of the servers, it’ll wait to hear back from them. Simultaneously, if any of the index’s partitions are resident on the coordinating node – search requests are dispatched to each of those partitions as well (disk-bound). - -. Those servers in the cluster that receive the “internal” request from the coordinating node will forward it to each of the index partitions they host (disk-bound). - -. Separate search requests that are dispatched concurrently to all index partitions resident within a server, and the server waits to hear back from them. - -. Once the server hears back from all the partitions it hosts, it merges the results obtained from each of the partitions before packaging them into a response and shipping it back to the coordinating node. - -The coordinating node waits for responses from: - -** each of the index partitions resident within the node -** each of the servers in the cluster that it dispatched the internal request to - -Once all the results from the local index partitions and the remote index partitions are obtained, the coordinating node merges all of them, packages them into a response, and ships them back to the client where the request originated. - -Full Text Search is powered by http://www.blevesearch.com/[Bleve^], an open source search and indexing library written in _Go_. -Full Text Search uses Bleve for the indexing of documents and also makes available Bleve’s extensive range of _query types_. -These include: - -* xref:fts-supported-queries-match.adoc[Match], xref:fts-supported-queries-match-phrase.adoc[Match Phrase] -* xref:fts-supported-queries-DocID-query.adoc[DocId Query], and xref:fts-supported-queries-prefix-query.adoc[Prefix Query] -* xref:fts-supported-queries-conjuncts-disjuncts.adoc[Conjuncts & Disjuncts], and xref:fts-supported-queries-boolean-field-query.adoc[Boolean] -* xref:fts-supported-queries-numeric-range.adoc[Numeric Range] and xref:fts-supported-queries-date-range.adoc[Date Range] -* xref:fts-supported-queries-geo-spatial.adoc[Geospatial] queries -* xref:fts-supported-queries-query-string-query.adoc[Query String Query] which employ a special syntax to express the details of each query. -* xref:fts-supported-queries-fuzzy.adoc[Fuzzy] -* xref:fts-supported-queries-regexp.adoc[Regexp] -* xref:fts-supported-queries-wildcard.adoc[Wildcard] -* xref:fts-supported-queries-boosting-the-score-query.adoc[Boosting the Score] - -Full Text Search includes pre-built text analyzers for multiple languages. For the current list of all supported languages in Couchbase Server refer to: xref:fts-index-analyzers.adoc#Supported-Languages[Supported Analyzer Languages] - -== Authorization for Full Text Search - -To access Full Text Search, users require appropriate _roles_. -The role *FTS Admin* must therefore be assigned to those who intend to create indexes; and the role *FTS Searcher* to those who intend to perform searches. -For information on creating users and assigning roles, see xref:learn:security/authorization-overview.adoc[Authorization]. - -// == FTS Application -// #Need Information# diff --git a/modules/fts/pages/fts-manage-index-lifecycle.adoc b/modules/fts/pages/fts-manage-index-lifecycle.adoc deleted file mode 100644 index 404f41c2fc..0000000000 --- a/modules/fts/pages/fts-manage-index-lifecycle.adoc +++ /dev/null @@ -1,26 +0,0 @@ -= Manage Index Lifecycle - -Full Text Indexes, once created can be cloned, edited and/or deleted. They are accessed from the *Search* tab: left-click on this to display the *Full Text Search* panel, which contains a tabular presentation of currently existing indexes, with a row for each index. - -(See xref:fts-searching-from-the-UI.adoc[Searching from the UI] for a full illustration.) - -To manage an index, left-click on its row. The row expands, as follows: - -[#fts_index_management_ui] -image::fts-index-management-ui.png[,820,align=left] - -== Edit Index - -* [.ui]*Edit* brings up the *Edit Index* screen, which allows the index to be modified. Saving modifications cause the index to be rebuilt. - -"Quick Edit" that goes to the quick editor for an index definition also results in the same functionalities. - -NOTE: Both the [.ui]*Edit Index* and [.ui]*Clone Index* screens are in most respects the same as the [.ui]*Add Index* screen, which was itself described in xref:fts-searching-from-the-UI.adoc[Searching from the UI]. - -== Delete Index - -* [.ui]*Delete* causes the current index to be deleted. Index deletion is an asynchronous process run in the background. - -== Clone Index - -* [.ui]*Clone* button click brings up the *Clone Index* screen, which allows a copy of the current index to be modified as appropriate and required, and saved under a new name. diff --git a/modules/fts/pages/fts-multi-collection-behaviour.adoc b/modules/fts/pages/fts-multi-collection-behaviour.adoc deleted file mode 100644 index f228e54f07..0000000000 --- a/modules/fts/pages/fts-multi-collection-behaviour.adoc +++ /dev/null @@ -1,220 +0,0 @@ -= Multi-Collection Behaviour - -Couchbase's FTS service is the only service that can create indexes that span collections. - -Multi-Collection Index: A user can search multi-collection indexes in the same way as that of a bucket-based index. Since a multi-collection index contains data from multiple source collections, it is helpful to know the source collection of every document xref:fts-search-response-hits.adoc[hit] in the search result. - -* Users can see the source collection names in the fields section of each document xref:fts-search-response-hits.adoc[hit] under the key _$c. See the image below for an example. - -image::fts-multi-collection-behaviour.png[,750,align=left] - -* Users can also narrow their full-text search requests to only specific Collection(s) within the multi-Collection index. This focus speeds up searches on a large index. - -Below is a sample Collection search request for Collections "airport". - -*Example* -[source,console] ----- -curl -XPOST -H “Content-Type:application/json” - u -: http://localhost:8094/api/index/demoindex/query -d - -‘{ - “explain”: true, - “fields”:[ - “*” - ], - “highlight”:{}, - “query”:{ - “query”:”france” - }, - “size”:10, - “from”:50, - “collections”:[“airport”] -}’ ----- - -* At search time, there is no validation to determine whether or not a collection with a given name exists. As a result, users won’t receive any validation errors for the incorrect collection names within the search request. -See the below example: - -*Example* - -An incorrect collection name “XYZ” is used. - -[source,console] ----- - -curl -XPOST -H “Content-Type:application/json” - u -: http://localhost:8094/api/index/demoindex/query -d -‘{ -“query”:{ -“query”:”france” -}, -“size”:10, -“from”:50, -“collections”:[“XYZ”] -}’ ----- - -*Result:* - -[source,json] ----- -Result: -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "query": "france" - }, - "size": 10, - "from": 50, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "-_score" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "demoindex_6dbcc808a8278714_4c1c5584", - "id": "hotel_21844", - "score": 0.8255329922213157, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - }, - { - "index": "demoindex_6dbcc808a8278714_4c1c5584", - "id": "hotel_21652", - "score": 0.8236828315727989, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - }, - { - "index": "demoindex_6dbcc808a8278714_4c1c5584", - "id": "hotel_1364", - "score": 0.8232253432142588, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - }, - { - "index": "demoindex_6dbcc808a8278714_4c1c5584", - "id": "hotel_21721", - "score": 0.8225069701742189, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - }, - { - "index": "demoindex_6dbcc808a8278714_4c1c5584", - "id": "hotel_21674", - "score": 0.8218917130827247, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - }, - { - "index": "demoindex_6dbcc808a8278714_4c1c5584", - "id": "hotel_35854", - "score": 0.8218917094653351, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - }, - { - "index": "demoindex_6dbcc808a8278714_4c1c5584", - "id": "hotel_21847", - "score": 0.8212458150010249, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - }, - { - "index": "demoindex_6dbcc808a8278714_4c1c5584", - "id": "hotel_21849", - "score": 0.8201164200350234, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - }, - { - "index": "demoindex_6dbcc808a8278714_4c1c5584", - "id": "hotel_21846", - "score": 0.8197896824791812, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - }, - { - "index": "demoindex_6dbcc808a8278714_4c1c5584", - "id": "hotel_20421", - "score": 0.8191068922164917, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - } - ], - "total_hits": 141, - "max_score": 1.0743017811485551, - "took": 999962, - "facets": null -} ----- - -== Impact of using Role-Based Access Control - -The Couchbase Full Admin can administer Role-Based Access Control (RBAC) roles for full-text search indexes at a Bucket, Scope, or Collection(s) level. - -FTS provides two primary roles for managing the access control: - -* xref:learn:security/roles.adoc#search-admin[Search Admin] -* xref:learn:security/roles.adoc#search-reader[Search Reader] - -A user must have at least search reader permissions at the source Bucket or Scope or Collection level to access the FTS index. - -NOTE: With multi-collection indexes, the user must have search reader roles for all source collections in order to access a multi-collection index. - -== Data lifecycle impact - -Multi-collection indexes are deleted when any of the corresponding source collections are deleted. Therefore, multi-collection indexes are best suited for collections with similar data lifespans. \ No newline at end of file diff --git a/modules/fts/pages/fts-perform-searches.adoc b/modules/fts/pages/fts-perform-searches.adoc deleted file mode 100644 index e8c3c3fead..0000000000 --- a/modules/fts/pages/fts-perform-searches.adoc +++ /dev/null @@ -1,22 +0,0 @@ -= Performing Searches -:page-aliases: fts-performing-searches.adoc - -Full text searches can be performed with: - -* The Couchbase Web Console. -This UI can also be used to create indexes and analyzers. -Refer to xref:fts-searching-from-the-ui.adoc[Searching from the UI] for information. - -* The Couchbase REST API. -Refer to xref:fts-searching-with-curl-http-requests.adoc[Searching with the REST API] for information. -Refer also to xref:rest-api:rest-fts.adoc[Full Text Search API] for REST reference details. - -* The Couchbase SDK. -This supports several languages, and allows full text searches to be performed with each. -Refer to the SDK's xref:java-sdk:concept-docs:full-text-search-overview.adoc[Full Text Search] page for information. - -NOTE: The xref:java-sdk:howtos:full-text-searching-with-sdk.adoc[Searching from the SDK] page for the _Java_ SDK provides an extensive code-example that demonstrates multiple options for performing full text searches. - -* The {sqlpp} Search functions. -These enable you to perform a full text search as part of a {sqlpp} query. -Refer to xref:n1ql:n1ql-language-reference/searchfun.adoc[Search Functions] for information. diff --git a/modules/fts/pages/fts-query-string-syntax-boosting.adoc b/modules/fts/pages/fts-query-string-syntax-boosting.adoc deleted file mode 100644 index c318177d29..0000000000 --- a/modules/fts/pages/fts-query-string-syntax-boosting.adoc +++ /dev/null @@ -1,32 +0,0 @@ -[#Boosting] -= Boosting - -When you specify multiple query-clauses, you can specify the relative importance to a given clause by suffixing it with the `^` operator, followed by a number or by specifying the `boost` parameter with the number to boost the search. - -== Example - -[source, json] ----- -description:pool name:pool^5 ----- - -The above syntax performs Match Queries for *pool* in both the `name` and `description` fields, but documents having the term in the `name` field score higher. - -[source, json] ----- -"query": { - ​​​​​  "disjuncts": [ -      { - ​​​​​"match": "glossop", - "field": "city", - "boost": 10 - }​​​​​, -      { - ​​​​​"match": "glossop", - "field": "title" - }​​​​​     - ]   -}​​​​​ ----- - -The above syntax performs Match Queries for a city *glossop* in both the `city` and `title` fields, but documents having the term in the `city` field score higher. \ No newline at end of file diff --git a/modules/fts/pages/fts-query-string-syntax-date-ranges.adoc b/modules/fts/pages/fts-query-string-syntax-date-ranges.adoc deleted file mode 100644 index 16fa578270..0000000000 --- a/modules/fts/pages/fts-query-string-syntax-date-ranges.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[#Date-Range] -= Date Range - -You can perform date range searches by using the `>`, `>=`, `<`, and `\<=` operators, followed by a date value in quotes. - -For example, `created:>"2016-09-21"` will perform a xref:fts-supported-queries-date-range.adoc[date range query] on the `created` field for values after September 21, 2016. \ No newline at end of file diff --git a/modules/fts/pages/fts-query-string-syntax-escaping.adoc b/modules/fts/pages/fts-query-string-syntax-escaping.adoc deleted file mode 100644 index 6f021d3f34..0000000000 --- a/modules/fts/pages/fts-query-string-syntax-escaping.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[#Escaping] -= Escaping - -The following quoted-string enumerates the characters which may be escaped: - ----- -"+-=&|>`, `>=`, `<`, and `\<=` operators, each followed by a numeric value. - -== Example - -`reviews.ratings.Cleanliness:>4` performs a xref:fts-supported-queries-numeric-range.adoc[numeric range query] on the `reviews.ratings.Cleanliness` field, for values greater than 4. \ No newline at end of file diff --git a/modules/fts/pages/fts-query-string-syntax.adoc b/modules/fts/pages/fts-query-string-syntax.adoc deleted file mode 100644 index 0a96358d13..0000000000 --- a/modules/fts/pages/fts-query-string-syntax.adoc +++ /dev/null @@ -1,15 +0,0 @@ -= Query String Syntax -:page-aliases: query-string-queries.adoc - -[abstract] -Query strings enable you to describe complex queries using a simple syntax. - -Using the query string syntax, the following query types can be performed: - -* xref:fts:fts-query-string-syntax-boosting.adoc[Boosting] -* xref:fts:fts-query-string-syntax-date-ranges.adoc[Date Range] -* xref:fts:fts-query-string-syntax-escaping.adoc[Escaping] -* xref:fts:fts-query-string-syntax-field-scoping.adoc[Field Scoping] -* xref:fts:fts-query-string-syntax-match-phrase.adoc[Match Phrase] -* xref:fts:fts-query-string-syntax-match.adoc[Match Query Syntax] -* xref:fts:fts-query-string-syntax-numeric-ranges.adoc[Numeric Range] \ No newline at end of file diff --git a/modules/fts/pages/fts-queryshape-circle.adoc b/modules/fts/pages/fts-queryshape-circle.adoc deleted file mode 100644 index ef33f2dc6a..0000000000 --- a/modules/fts/pages/fts-queryshape-circle.adoc +++ /dev/null @@ -1,468 +0,0 @@ -= Circle Query - -[abstract] -A GeoJSON Circle Query against any GeoJSON type. - -== QueryShape for a Circle Query - -A GeoJSON query via a GeoShape of Circle to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within. - -A Circle represents a disc shape on the earth’s spherical surface. This is a Couchbase extension to GeoJSON. - -For full details on formats for the radius refer to xref:fts-supported-queries-geojson-spatial.adoc#specifying-distances[Distances] - -=== Circle `Intersects` Query - -An `intersect` query for the circle returns all the matched documents with shapes that overlap with the area of the circular shape in the query. - -A circle `intersection` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "coordinates": [ - -2.235143, - 53.482358 - ], - "type": "circle", - "radius": "100mi" - }, - "relation": "intersects" - } - } -} ----- - -Intersection rules for the Circle Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Intersects (relation) + -Document Shape|{nbsp} + -Circle (GeoShape) - -| Point -| Intersects if the point lies within the circular region. - -| LineString -| Intersects if the line cuts/goes through anywhere within the circular region. - -| Polygon -| Intersects if there is an area overlap between the polygon and the circular region in the query. - -| MultiPoint -| Intersects if any of the points lie within the circular region. - -| MultiLineString -| Intersects if any of the lines cut/go through anywhere within the circular region. - -| MultiPolygon -| Intersects if there is an area overlap between any of the polygons in the multipolygon array and the circular region in the query. - -| GeometryCollection -| Intersects if there is an overlap between any of the heterogeneous (above 6) shapes in the geometrycollection array in the document with the query circle. - -| Circle -| Intersects if the area of the circle intersects with the query circle. - -| Envelope -| Intersects if the area of the rectangle intersects with the query circle. - -|=== - -=== Circle `Contains` Query - -A `contain` query for the circle returns all the matched documents with shapes that completely contain the area of the circular shape in the query. - -A circle `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "coordinates": [ - -2.235143, - 53.482358 - ], - "type": "circle", - "radius": "100mi" - }, - "relation": "contains" - } - } -} ----- - -Containment rules for the Circle Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Contains (relation) + -Document Shape|{nbsp} + -Circle (GeoShape) - -| Point -| NA. Points can’t cover a circle. - -| LineString -| NA. LineStrings can’t cover a circle. - -| Polygon -| Matches if the polygon area contains the circular region in the query. - -| MultiPoint -| NA. MultiPoints can’t cover a circle. - -| MultiLineString -| NA. MultiLineStrings can’t cover a circle. - -| MultiPolygon -| Matches if any of the polygons in the multipolygon array contains the circular region in the query. - -| GeometryCollection -| Matches if there is a containment between any of the heterogeneous (above 6) shapes in the geometrycollection array in the document with the query circle. - -| Circle -| Matches if the area of the document circle contains the query circle. - -| Envelope -| Matches if the area of the document rectangle contains the query circle. - -|=== - -=== Circle `WithIn` Query - -The Within query is not supported by line geometries. - -A `within` query for the circle returns all the matched documents with shapes that are completely residing within the area of the circular shape in the query. -A circle `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "coordinates": [ - -2.235143, - 53.482358 - ], - "type": "circle", - "radius": "100mi" - }, - "relation": "within" - } - } -} ----- - -WithIn rules for the Circle Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Contains (relation) + -Document Shape|{nbsp} + -Circle (GeoShape) - -| Point -| Matches if the point lies within the circular region. - -| LineString -| Matches if the linestring lies within the circular region. - -| Polygon -| Matches if the polygon area is residing within the query circle. - -| MultiPoint -| Matches if all the points in the array lie within the circular region. - -| MultiLineString -| Matches if all the linestrings in the array lie within the circular region. - -| MultiPolygon -| Matches if every polygon area is residing completely within the circular region in the query. - -| GeometryCollection -| Matches if there is a complete containment between every heterogeneous (above 6) shapes in the geometrycollection array in the document and the query circle. - -| Circle -| Matches if the document circle resides within the query circle. - -| Envelope -| Matches if the document rectangle resides within the query circle. - -|=== - -== Example Circle Query (against Points) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Intersects if the point lies within the circular region. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "geometry": { - "shape": { - "coordinates": [ - -2.235143, - 53.482358 - ], - "type": "circle", - "radius": "100mi" - }, - "relation": "intersects" - }, - "field": "geojson" - }, - "size": 10, - "from": 0, - "sort": [ - { - "by": "geo_distance", - "field": "geojson", - "unit": "mi", - "location": { - "lon": -2.235143, - "lat": 53.482358 - } - } - ], - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of five (5) hits (from a total of 842 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "circle", - "coordinates": [ - -2.235143, - 53.482358 - ], - "radiusInMeters": 160934.4 - }, - "relation": "intersects" - }, - "field": "geojson" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "hotel_15466", - "score": 0.48460386356013374, - "sort": [ - "8 Clarendon Crescent" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "landmark_3548", - "score": 0.2153234885704102, - "sort": [ - "AMC" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "landmark_570", - "score": 0.12120554320433605, - "sort": [ - "Abacus Books" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "landmark_6350", - "score": 0.27197802451106445, - "sort": [ - "Aberconwy House" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "hotel_40", - "score": 0.2929891838246811, - "sort": [ - "Aberdovey Hillside Village" - ] - } - ], - "total_hits": 842, - "max_score": 0.5928042064997198, - "took": 24655382, - "facets": null -} ----- - -== Example Circle Query (against Circles) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Matches if the document circle resides within the query circle. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "geometry": { - "shape": { - "coordinates": [ - -2.235143, - 53.482358 - ], - "type": "circle", - "radius": "100mi" - }, - "relation": "within" - }, - "field": "geoarea" - }, - "size": 10, - "from": 0, - "sort": [ - { - "by": "geo_distance", - "field": "geojson", - "unit": "mi", - "location": { - "lon": -2.235143, - "lat": 53.482358 - } - } - ], - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of five (5) hits (from a total of 36 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "circle", - "coordinates": [ - -2.235143, - 53.482358 - ], - "radiusInMeters": 160934.4 - }, - "relation": "within" - }, - "field": "geoarea" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_577", - "score": 0.1543972016608065, - "sort": [ - "Barkston Heath" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_469", - "score": 0.5853253239353176, - "sort": [ - "Birmingham" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_514", - "score": 0.14663352685195305, - "sort": [ - "Blackpool" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_511", - "score": 0.19445510224080859, - "sort": [ - "Brough" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_568", - "score": 0.1561033061076272, - "sort": [ - "Church Fenton" - ] - } - ], - "total_hits": 36, - "max_score": 1.015720869823755, - "took": 8549509, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-queryshape-envelope.adoc b/modules/fts/pages/fts-queryshape-envelope.adoc deleted file mode 100644 index 254a6df425..0000000000 --- a/modules/fts/pages/fts-queryshape-envelope.adoc +++ /dev/null @@ -1,446 +0,0 @@ -= Envelope Query - -[abstract] -A GeoJSON Envelope Query against any GeoJSON type. - -== QueryShape for an Envelope Query - -A GeoJSON query via a GeoShape of Envelope to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within. - -Also called a bounded rectangle query by specifying +++[[minLon, maxLat], [maxLon, minLat]]+++. This is a Couchbase extension to GeoJSON. - -=== Envelope `Intersects` Query - -An `intersect` query for the envelope returns all the matched documents with shapes that overlap with the area of the rectangle shape in the query. - -A envelope `intersection` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "Envelope", - "coordinates": [ - [-2.235143, 53.482358], - [28.955043, 40.991862] - ] - }, - "relation": "intersects" - } - } -} ----- - -Intersection rules for the Envelope Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Intersects (relation) + -Document Shape|{nbsp} + -Envelope (GeoShape) - -| Point -| Matches if the point lies within the query rectangle region. - -| LineString -| Matches if the linestring intersects or lies within the query rectangle. - -| Polygon -| Matches if the polygon area is overlapping the query rectangle. - -| MultiPoint -| Matches if any of the points in the array lie within the rectangle region. - -| MultiLineString -| Matches if any of the linestrings intersect or lie within the rectangle area. - -| MultiPolygon -| Matches if any of the polygon areas is overlapping the rectangle region. - -| GeometryCollection -| Matches if there is an overlap between any heterogeneous (above 6) shapes in the geometrycollection array in the document and the query rectangle. - -| Circle -| Matches if the area of the query rectangle overlaps the document circle. - -| Envelope -| Matches if the query rectangle overlaps the document rectangle area. - -|=== - -=== Envelope `Contains` Query - -A `contains` query for the envelope returns all the matched documents with shapes that contain the area of the rectangle shape in the query. - -A envelope `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [-2.235143, 53.482358], - [28.955043, 40.991862] - ] - }, - "relation": "contains" - } - } -} ----- - -Containment rules for the Envelope Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Contains (relation) + -Document Shape|{nbsp} + -Envelope (GeoShape) - -| Point -| NA, Point can’t contain an envelope. - -| LineString -| NA, LineString can’t contain an envelope. - -| Polygon -| Matches if the polygon area is containing the rectangle region in the query. - -| MultiPoint -| NA, MultiPoint can’t contain an envelope. - -| MultiLineString -| NA, MultiLineString can’t contain an envelope. - -| MultiPolygon -| Matches if any of the polygon areas contains the entire rectangle region. - -| GeometryCollection -| Matches if there is a containment between any heterogeneous (above 6) shapes in the geometrycollection array in the document and the query rectangle. - -| Circle -| Matches if the query rectangle resides within the document circle. - -| Envelope -| Matches if the query rectangle resides within the document rectangle. - -|=== - -=== Envelope `WithIn` Query - -The Within query is not supported by line geometries. - -A `within` query for the envelope returns all the matched documents with shapes that are contained within the area of the rectangle shape in the query. - -A envelope `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [-2.235143, 53.482358], - [28.955043, 40.991862] - ] - }, - "relation": "within" - } - } -} ----- - -WithIn rules for the Envelope Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Contains (relation) + -Document Shape|{nbsp} + -Envelope (GeoShape) - -| Point -| Matches if the point lies within the query rectangle region. - -| LineString -| Matches if the linestring resides completely within the query rectangle. - -| Polygon -| Matches if the polygon resides completely within the query rectangle. - -| MultiPoint -| Matches if all the points in the array lie within the query rectangle. - -| MultiLineString -| Matches if all the linestrings lie within the query rectangle area. - -| MultiPolygon -| Matches if all the polygons reside within the query rectangle region. - -| GeometryCollection -| Matches if there is within relation between all the heterogeneous (above 6) shapes in the geometrycollection array in the document and the query rectangle. - -| Circle -| Matches if the document circle resides within the query rectangle. - -| Envelope -| Matches if the document rectangle resides within the query rectangle. - -|=== - -== Example Envelope Query (against Points) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Matches if the point lies within the query rectangle region. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geojson", - "geometry": { - "shape": { - "type": "Envelope", - "coordinates": [ - [-2.235143, 53.482358], - [28.955043, 40.991862] - ] - }, - "relation": "within" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of five (5) hits (from a total of 2024 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "Envelope", - "coordinates": [ - [ - -2.235143, - 53.482358 - ], - [ - 28.955043, - 40.991862 - ] - ] - }, - "relation": "within" - }, - "field": "geojson" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "hotel_1364", - "score": 0.05896334942635901, - "sort": [ - "'La Mirande Hotel" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "landmark_16144", - "score": 0.004703467956838207, - "sort": [ - "02 Shepherd's Bush Empire" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "landmark_16181", - "score": 0.004703467956838207, - "sort": [ - "2 Willow Road" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "landmark_16079", - "score": 0.004703467956838207, - "sort": [ - "20 Fenchurch Street" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "landmark_40437", - "score": 0.004703467956838207, - "sort": [ - "30 St. Mary Axe" - ] - } - ], - "total_hits": 2024, - "max_score": 0.12470500060351324, - "took": 17259514, - "facets": null -} ----- - -== Example Envelope Query (against Circles) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Matches if the area of the query rectangle overlaps the document circle. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geoarea", - "geometry": { - "shape": { - "type": "Envelope", - "coordinates": [ - [-2.235143, 53.482358], - [28.955043, 40.991862] - ] - }, - "relation": "intersects" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of five (5) hits (from a total of 293 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "Envelope", - "coordinates": [ - [ - -2.235143, - 53.482358 - ], - [ - 28.955043, - 40.991862 - ] - ] - }, - "relation": "intersects" - }, - "field": "geoarea" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1372", - "score": 0.008758192642105457, - "sort": [ - "Abbeville" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1294", - "score": 0.07778849955604289, - "sort": [ - "Aire Sur L Adour" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1329", - "score": 0.009493654411662942, - "sort": [ - "Aix Les Bains" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1347", - "score": 0.06002598189280991, - "sort": [ - "Aix Les Milles" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_8588", - "score": 0.010149143194537646, - "sort": [ - "All Airports" - ] - } - ], - "total_hits": 293, - "max_score": 0.4253566663133814, - "took": 13358586, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-queryshape-geometrycollection.adoc b/modules/fts/pages/fts-queryshape-geometrycollection.adoc deleted file mode 100644 index 40fea60a87..0000000000 --- a/modules/fts/pages/fts-queryshape-geometrycollection.adoc +++ /dev/null @@ -1,612 +0,0 @@ -= GeometryCollection Query - -[abstract] -A GeoJSON GeometryCollection Query against any GeoJSON type. - -== QueryShape for a GeometryCollection Query - -A GeoJSON query via a GeoShape of GeometryCollection to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within. - -=== GeometryCollection `Intersects` Query - -An `intersect` query for geometrycollection returns all the matched documents with shapes that overlap with the area of any of the shapes in the geometrycollection array within the query. - -A geometrycollection `intersection` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "geometrycollection", - "geometries": [{ - "type": "linestring", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, { - "type": "multipolygon", - "coordinates": [ - [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ], - [ - [ - [-109.05029296875, 37.00255267215955], - [-102.041015625, 37.00255267215955], - [-102.041015625, 40.9964840143779], - [-109.05029296875, 40.9964840143779], - [-109.05029296875, 37.00255267215955] - ] - ] - ] - }] - }, - "relation": "intersects" - } - } -} ----- - -The intersection rules are similar to that of the respective shapes composed within the GeometryCollection array. -The rules will be applied to any indexed GeoJSON shape in the array. -If any of the query shapes within the geometries array intersects with any of the indexed shapes, then it will be a matching document. - -=== GeometryCollection `Contains` Query - -A `contains` query for geometrycollection returns all the matched documents with shapes that contain the geometrycollection within the query. - -A geometrycollection `contains` query sample is given below. - -[source, json] ----- -{{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "geometrycollection", - "geometries": [{ - "type": "linestring", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, { - "type": "multipolygon", - "coordinates": [ - [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ], - [ - [ - [-109.05029296875, 37.00255267215955], - [-102.041015625, 37.00255267215955], - [-102.041015625, 40.9964840143779], - [-109.05029296875, 40.9964840143779], - [-109.05029296875, 37.00255267215955] - ] - ] - ] - }] - }, - "relation": "contains" - } - } -} ----- - -The containment rules are similar to that of the respective shapes composed within the GeometryCollection array. -The rules will be applied to any indexed GeoJSON shape in the array. -If all of the query shapes within the geometries array contained within any (cumulatively) of the indexed shapes completely, then it will be a matching document. - -=== GeometryCollection `WithIn` Query - -The Within query is not supported by line geometries. - -A `within` query for geometrycollection returns all the matched documents with shapes that contain the geometrycollection within the query. - -A geometrycollection `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "geometrycollection", - "geometries": [{ - "type": "linestring", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, { - "type": "multipolygon", - "coordinates": [ - [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ], - [ - [ - [-109.05029296875, 37.00255267215955], - [-102.041015625, 37.00255267215955], - [-102.041015625, 40.9964840143779], - [-109.05029296875, 40.9964840143779], - [-109.05029296875, 37.00255267215955] - ] - ] - ] - }] - }, - "relation": "within" - } - } -} ----- - -The within rules are similar to that of the respective shapes composed within the GeometryCollection array. -The rules will be applied to any indexed GeoJSON shape in the array. -If any of the query shapes within the geometries array contain any of the indexed shapes completely, then it will be a matching document. - -== Example GeometryCollection Query (against Points) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Matches when the geometrycollection in the query contains the point in the document including points on the edge or coinciding with the vertices of the geometrycollection. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geojson", - "geometry": { - "shape": { - "type": "geometrycollection", - "geometries": [{ - "type": "linestring", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, { - "type": "multipolygon", - "coordinates": [ - [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ], - [ - [ - [-109.05029296875, 37.00255267215955], - [-102.041015625, 37.00255267215955], - [-102.041015625, 40.9964840143779], - [-109.05029296875, 40.9964840143779], - [-109.05029296875, 37.00255267215955] - ] - ] - ] - }] - }, - "relation": "intersects" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of five (5) hits (from a total of 47 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "geometrycollection", - "geometries": [ - { - "type": "linestring", - "coordinates": [ - [ - 1.954764, - 50.962097 - ], - [ - 3.029578, - 49.868547 - ] - ] - }, - { - "type": "multipolygon", - "coordinates": [ - [ - [ - [ - -114.027099609375, - 42.00848901572399 - ], - [ - -114.04907226562499, - 36.99377838872517 - ], - [ - -109.05029296875, - 36.99377838872517 - ], - [ - -109.05029296875, - 40.98819156349393 - ], - [ - -111.060791015625, - 40.98819156349393 - ], - [ - -111.02783203125, - 42.00848901572399 - ], - [ - -114.027099609375, - 42.00848901572399 - ] - ] - ], - [ - [ - [ - -109.05029296875, - 37.00255267215955 - ], - [ - -102.041015625, - 37.00255267215955 - ], - [ - -102.041015625, - 40.9964840143779 - ], - [ - -109.05029296875, - 40.9964840143779 - ], - [ - -109.05029296875, - 37.00255267215955 - ] - ] - ] - ] - } - ] - }, - "relation": "intersects" - }, - "field": "geojson" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7001", - "score": 0.06568712770601859, - "sort": [ - "Aspen Pitkin County Sardy Field" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_8854", - "score": 0.03222560611574136, - "sort": [ - "Boulder Municipal" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_6999", - "score": 0.030963288954845132, - "sort": [ - "Brigham City" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7857", - "score": 0.06475045434251171, - "sort": [ - "Bryce Canyon" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_3567", - "score": 0.03222560611574136, - "sort": [ - "Buckley Afb" - ] - } - ], - "total_hits": 47, - "max_score": 0.23169125425271897, - "took": 32362669, - "facets": null -} ----- - -== Example GeometryCollection Query (against Circles) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Intersects when the query geometrycollection intersects the circular region in the document. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geoarea", - "geometry": { - "shape": { - "type": "geometrycollection", - "geometries": [{ - "type": "linestring", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, { - "type": "multipolygon", - "coordinates": [ - [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ], - [ - [ - [-109.05029296875, 37.00255267215955], - [-102.041015625, 37.00255267215955], - [-102.041015625, 40.9964840143779], - [-109.05029296875, 40.9964840143779], - [-109.05029296875, 37.00255267215955] - ] - ] - ] - }] - }, - "relation": "intersects" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of five (5) hits (from a total of 52 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "geometrycollection", - "geometries": [ - { - "type": "linestring", - "coordinates": [ - [ - 1.954764, - 50.962097 - ], - [ - 3.029578, - 49.868547 - ] - ] - }, - { - "type": "multipolygon", - "coordinates": [ - [ - [ - [ - -114.027099609375, - 42.00848901572399 - ], - [ - -114.04907226562499, - 36.99377838872517 - ], - [ - -109.05029296875, - 36.99377838872517 - ], - [ - -109.05029296875, - 40.98819156349393 - ], - [ - -111.060791015625, - 40.98819156349393 - ], - [ - -111.02783203125, - 42.00848901572399 - ], - [ - -114.027099609375, - 42.00848901572399 - ] - ] - ], - [ - [ - [ - -109.05029296875, - 37.00255267215955 - ], - [ - -102.041015625, - 37.00255267215955 - ], - [ - -102.041015625, - 40.9964840143779 - ], - [ - -109.05029296875, - 40.9964840143779 - ], - [ - -109.05029296875, - 37.00255267215955 - ] - ] - ] - ] - } - ] - }, - "relation": "intersects" - }, - "field": "geoarea" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7001", - "score": 0.044156513771700656, - "sort": [ - "Aspen Pitkin County Sardy Field" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_8854", - "score": 0.021237915321935485, - "sort": [ - "Boulder Municipal" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1258", - "score": 0.4165991857145269, - "sort": [ - "Bray" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_6999", - "score": 0.01797996798708474, - "sort": [ - "Brigham City" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7857", - "score": 0.09702723621245812, - "sort": [ - "Bryce Canyon" - ] - } - ], - "total_hits": 52, - "max_score": 0.8460432736575045, - "took": 18306647, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-queryshape-linestring.adoc b/modules/fts/pages/fts-queryshape-linestring.adoc deleted file mode 100644 index a1dc23ac45..0000000000 --- a/modules/fts/pages/fts-queryshape-linestring.adoc +++ /dev/null @@ -1,361 +0,0 @@ -= LineString Query - -[abstract] -A GeoJSON LineString Query against any GeoJSON type. - -== QueryShape for a LineString Query - -A GeoJSON query via a GeoShape of LineString to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within. - -=== LineString `Intersects` Query - -A `contains` query for linestring returns all the matched documents with shapes that intersect the linestring within the query. - -A linestring `intersection` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "linestring", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, - "relation": "intersects" - } - } -} ----- - -Intersection rules for the LineString Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Intersects (relation) + -Document Shape|{nbsp} + -LineString (GeoShape) - -| Point -| Intersects when any of the line endpoints overlap the point in the document. - -| LineString -| Intersects when the linestring in the query intersects the linestring in the document. - -| Polygon -| Intersects when the linestring in the query intersects any of the edges of the polygon in the document. - -| MultiPoint -| Intersects when any of the line endpoints overlap any of the points in the multipoint array in the document. - -| MultiLineString -| Intersects when the linestring in the query intersects any of the linestring in the multilinestring array in the document. - -| MultiPolygon -| Intersects when the linestring in the query intersects any of the edges of any of the polygons in the multipolygon array in the document. - -| GeometryCollection -| Matches when the query point overlaps with any of the heterogeneous (above 6) shapes in the geometrycollection array in the document. - -| Circle -| Intersects when the query point lies within the area of the circular region in the document. - -| Envelope -| Intersects when the query point lies within the area of the rectangular/bounded box region in the document. - -|=== - -=== LineString `Contains` Query - -A `contains` query for linestring returns all the matched documents with shapes that contain the linestring within the query. - -A linestring `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "linestring", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, - "relation": "contains" - } - } -} ----- - -Containment rules for the LineString Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Contains (relation) + -Document Shape|{nbsp} + -LineString (GeoShape) - -| Point (document shape) -| NA. As the point is a non-closed shape. - -| LineString -| NA. As a linestring is a non-closed shape. - -| Polygon -| Contains when both the endpoints(start, end) of the linestring in the query are within the area of the polygon in the document. - -| MultiPoint -| NA. As the multipoint is a non-closed shape. - -| MultiLineString -| NA. As the multilinestring is a non-closed shape. - -| MultiPolygon -| Contains when both the endpoints(start, end) of the linestring in the query are within the area of any of the polygons in the multipolygon array in the document. - -| GeometryCollection -| Matches when both the endpoints(start, end) of the linestring in query overlaps with any of the heterogeneous (above 6) shapes in the geometrycollection array in the document. - -| Circle -| Contains when both the endpoints(start, end) of the linestring in the query are within the area of the circular shape in the document. - -| Envelope -| Contains when both the endpoints(start, end) of the linestring in the query are within the area of the rectangle in the document. - -|=== - -=== LineString `WithIn` Query - -The Within query is not supported by line geometries. - -== Example LineString Query (against Points) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Intersects when any of the line endpoints overlap the point in the document. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "fields": ["name"], - "query": { - "field": "geojson", - "geometry": { - "shape": { - "type": "linestring", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, - "relation": "intersects" - } - }, - "sort": ["name"] -}' | jq . ----- - -The output of two (2) hits (from a total of 2 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "linestring", - "coordinates": [ - [ - 1.954764, - 50.962097 - ], - [ - 3.029578, - 49.868547 - ] - ] - }, - "relation": "intersects" - }, - "field": "geojson" - }, - "size": 10, - "from": 0, - "highlight": null, - "fields": [ - "name" - ], - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1254", - "score": 0.28065220923315787, - "sort": [ - "Calais Dunkerque" - ], - "fields": { - "name": "Calais Dunkerque" - } - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1255", - "score": 0.7904517545191571, - "sort": [ - "Peronne St Quentin" - ], - "fields": { - "name": "Peronne St Quentin" - } - } - ], - "total_hits": 2, - "max_score": 0.7904517545191571, - "took": 13592354, - "facets": null -} ----- - -== Example LineString Query (against Circles) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Intersects when the query point lies within the area of the circular region in the document. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "fields": ["name"], - "query": { - "field": "geoarea", - "geometry": { - "shape": { - "type": "linestring", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, - "relation": "intersects" - } - }, - "sort": ["name"] -}' | jq . ----- - -The output of three (3) hits (from a total of 3 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "linestring", - "coordinates": [ - [ - 1.954764, - 50.962097 - ], - [ - 3.029578, - 49.868547 - ] - ] - }, - "relation": "intersects" - }, - "field": "geoarea" - }, - "size": 10, - "from": 0, - "highlight": null, - "fields": [ - "name" - ], - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1258", - "score": 1.4305136320748595, - "sort": [ - "Bray" - ], - "fields": { - "name": "Bray" - } - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1254", - "score": 0.20713889888331502, - "sort": [ - "Calais Dunkerque" - ], - "fields": { - "name": "Calais Dunkerque" - } - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1255", - "score": 2.905133945992968, - "sort": [ - "Peronne St Quentin" - ], - "fields": { - "name": "Peronne St Quentin" - } - } - ], - "total_hits": 3, - "max_score": 2.905133945992968, - "took": 6943298, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-queryshape-multilinestring.adoc b/modules/fts/pages/fts-queryshape-multilinestring.adoc deleted file mode 100644 index fa16931f82..0000000000 --- a/modules/fts/pages/fts-queryshape-multilinestring.adoc +++ /dev/null @@ -1,331 +0,0 @@ -= MultiLineString Query - -[abstract] -A GeoJSON MultiLineString Query against any GeoJSON type. - -== QueryShape for a MultiLineString Query - -A GeoJSON query via a GeoShape of MultiLineString to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within. - -=== MultiLineString `Intersects` Query - -An `intersect` query for multilinestring returns all the matched documents with shapes that overlap any of the multiple linestring in the multilinestring array within the query. - -A multilinestring `intersection` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "MultiLineString", - "coordinates": [ - [ [1.954764, 50.962097], [3.029578, 49.868547] ], - [ [3.029578, 49.868547], [-0.387444, 48.545836] ] - ] - }, - "relation": "intersects" - } - } -} ----- - -Intersection rules for the MultiLineString Query with other indexed GeoJSON shapes in the document set are given below. - -Intersection rules for the MultiLineString Query with other indexed GeoJSON shapes are similar to that of the LineString shape mentioned here. -The only difference will be that intersection rules are applied on every LineString instance inside the MultiLineString array. - -=== MultiLineString `Contains` Query - -A `contains` query for multilinestring returns all the matched documents with shapes that contain the multilinestring within the query. - -A multilinestring `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "MultiLineString", - "coordinates": [ - [ [1.954764, 50.962097], [3.029578, 49.868547] ], - [ [3.029578, 49.868547], [-0.387444, 48.545836] ] - ] - }, - "relation": "contains" - } - } -} ----- - -Containment rules for the MultiLineString Query with other GeoJSON indexed shapes are similar to that of the LineString shape mentioned earlier. -The only difference will be that to qualify a match operation, the containment rules have to be satisfied by every LineString instance inside the MultiLineString array. - -=== MultiLineString `WithIn` Query - -The Within query is not supported by line geometries. - -A `within` query for multilinestring returns all the matched documents with shapes that contain the multilinestring within the query. - -A multilinestring `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "MultiLineString", - "coordinates": [ - [ [1.954764, 50.962097], [3.029578, 49.868547] ], - [ [3.029578, 49.868547], [-0.387444, 48.545836] ] - ] - }, - "relation": "within" - } - } -} ----- - -== Example MultiLineString Query (against Points) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Matches when the multilinestring in the query contains the point in the document including points on the edge or coinciding with the vertices of the multilinestring. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geojson", - "geometry": { - "shape": { - "type": "MultiLineString", - "coordinates": [ - [ [1.954764, 50.962097], [3.029578, 49.868547] ], - [ [3.029578, 49.868547], [-0.387444, 48.545836] ] - ] }, - "relation": "intersects" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of three (3) hits (from a total of 3 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "MultiLineString", - "coordinates": [ - [ - [ - 1.954764, - 50.962097 - ], - [ - 3.029578, - 49.868547 - ] - ], - [ - [ - 3.029578, - 49.868547 - ], - [ - -0.387444, - 48.545836 - ] - ] - ] - }, - "relation": "intersects" - }, - "field": "geojson" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1254", - "score": 0.11785430845172559, - "sort": [ - "Calais Dunkerque" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1257", - "score": 0.06113505132837742, - "sort": [ - "Couterne" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1255", - "score": 0.33193447914716134, - "sort": [ - "Peronne St Quentin" - ] - } - ], - "total_hits": 3, - "max_score": 0.33193447914716134, - "took": 26684141, - "facets": null -} ----- - -== Example MultiLineString Query (against Circles) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Intersects when the query multilinestring intersects the circular region in the document. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geoarea", - "geometry": { - "shape": { - "type": "MultiLineString", - "coordinates": [ - [ [1.954764, 50.962097], [3.029578, 49.868547] ], - [ [3.029578, 49.868547], [-0.387444, 48.545836] ] - ] }, - "relation": "intersects" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of three (3) hits (from a total of 3 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "MultiLineString", - "coordinates": [ - [ - [ - 1.954764, - 50.962097 - ], - [ - 3.029578, - 49.868547 - ] - ], - [ - [ - 3.029578, - 49.868547 - ], - [ - -0.387444, - 48.545836 - ] - ] - ] - }, - "relation": "intersects" - }, - "field": "geoarea" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1258", - "score": 0.592776664360894, - "sort": [ - "Bray" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1254", - "score": 0.08583427853207237, - "sort": [ - "Calais Dunkerque" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1255", - "score": 1.7695025992268105, - "sort": [ - "Peronne St Quentin" - ] - } - ], - "total_hits": 3, - "max_score": 1.7695025992268105, - "took": 3894224, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-queryshape-multipoint.adoc b/modules/fts/pages/fts-queryshape-multipoint.adoc deleted file mode 100644 index 629e2a39c7..0000000000 --- a/modules/fts/pages/fts-queryshape-multipoint.adoc +++ /dev/null @@ -1,396 +0,0 @@ -= MultiPoint Query - -[abstract] -A GeoJSON MultiPoint Query against any GeoJSON type. - -== QueryShape for a MultiPoint Query - -A GeoJSON query via a GeoShape of MultiPoint to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within. - -=== MultiPoint `Intersects` Query - -An `intersect` query for multipoint returns all the matched documents with shapes that overlap any of the multiple points in the multipoint array within the query. - -A multipoint `intersection` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "MultiPoint", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, - "relation": "intersects" - } - } -} ----- - -Intersection rules for the MultiPoint Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Intersects (relation) + -Document Shape|{nbsp} + -MultiPoint (GeoShape) - -| Point -| Intersects when any of the query points overlaps the point in the document. (as point is a non-closed shapes) - -| LineString -| Intersects when any of the query points overlaps with any of the line endpoints in the document.(as linestring is a non-closed shapes) - -| Polygon -| Intersects when any of the query points lies within the area of the polygon. - -| MultiPoint -| Intersects when any of the query points overlaps with any of the many points in the multipoint array in the document. - -| MultiLineString -| Intersects when any of the query points overlaps with any of the linestring endpoints in the multilinestring array in the document. - -| MultiPolygon -| Intersects when any of the query points lies within the area of any of the polygons in the multipolygon array in the document. - -| GeometryCollection -| Intersects when any of the query points overlaps with any of the heterogeneous (above 6) shapes in the geometrycollection array in the document. - -| Circle -| Intersects when any of the query points lies within the area of the circular region in the document. - -| Envelope -| Intersects when any of the query points lies within the area of the rectangular/bounded box region in the document. - -|=== - -=== MultiPoint `Contains` Query - -A `contains` query for multipoint returns all the matched documents with shapes that contain the multipoint within the query. - -A multipoint `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "MultiPoint", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, - "relation": "contains" - } - } -} ----- - -Containment rules for the MultiPoint Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Contains (relation) + -Document Shape|{nbsp} + -MultiPoint (GeoShape) - -| Point -| NA. A point can’t contain a multipoint. - -| LineString -| NA. A linestring can’t contain a multipoint. - -| Polygon -| Contains when all of the query points in the multipoint array lie within the area of the polygon. - -| MultiPoint -| Contains when all of the query points in the multipoint array overlap with any of the many points in the multipoint array in the document. - -| MultiLineString -| NA. A multi linestring can’t contain a multipoint. - -| MultiPolygon -| Contains when all of the query points in the multipoint array lie within the area of any of the polygons in the multipolygon array in the document. - -| GeometryCollection -| Contains when all of the query points in the multipoint array overlap with any of the heterogeneous (above 6) shapes in the geometrycollection array in the document. - -| Circle -| Contains when all of the query points in the multipoint array lie within the area of the circular region in the document. - -| Envelope -| Contains when all of the query points in the multipoint array lie within the area of the rectangular/bounded box region in the document. - -|=== - -=== MultiPoint `WithIn` Query - -The Within query is not supported by line geometries. - -A `within` query for multipoint returns all the matched documents with shapes that contain the multipoint within the query. - -A multipoint `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "MultiPoint", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, - "relation": "within" - } - } -} ----- - -WithIn rules for the MultiPoint Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Contains (relation) + -Document Shape|{nbsp} + -MultiPoint (GeoShape) - -| Point -| Matches when any of the query points in the multipoint array overlap with the geo points in the document. - -| LineString -| NA. - -| Polygon -| NA - -| MultiPoint -| Matches when all of the query points in the multipoint array overlap with any of the many points in the multipoint array in the document. - -| MultiLineString -| NA - -| MultiPolygon -| NA - -| GeometryCollection -| NA - -| Circle -| NA - -| Envelope -| NA - -|=== - -== Example MultiPoint Query (against Points) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Matches when any of the query points in the multipoint array overlap with the geo points in the document. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geojson", - "geometry": { - "shape": { - "type": "MultiPoint", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, - "relation": "within" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of two (2) hits (from a total of 2 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "MultiPoint", - "coordinates": [ - [ - 1.954764, - 50.962097 - ], - [ - 3.029578, - 49.868547 - ] - ] - }, - "relation": "within" - }, - "field": "geojson" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1254", - "score": 3.5287254429876733, - "sort": [ - "Calais Dunkerque" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1255", - "score": 3.5326647348568896, - "sort": [ - "Peronne St Quentin" - ] - } - ], - "total_hits": 2, - "max_score": 3.5326647348568896, - "took": 10149092, - "facets": null -} ----- - -== Example MultiPoint Query (against Circles) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Intersects when any of the query points lies within the area of the circular region in the document. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geoarea", - "geometry": { - "shape": { - "type": "MultiPoint", - "coordinates": [ - [1.954764, 50.962097], - [3.029578, 49.868547] - ] - }, - "relation": "intersects" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of two (2) hits (from a total of 2 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "MultiPoint", - "coordinates": [ - [ - 1.954764, - 50.962097 - ], - [ - 3.029578, - 49.868547 - ] - ] - }, - "relation": "intersects" - }, - "field": "geoarea" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1254", - "score": 0.490187283157727, - "sort": [ - "Calais Dunkerque" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1255", - "score": 0.7869533596268505, - "sort": [ - "Peronne St Quentin" - ] - } - ], - "total_hits": 2, - "max_score": 0.7869533596268505, - "took": 7023893, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-queryshape-multipolygon.adoc b/modules/fts/pages/fts-queryshape-multipolygon.adoc deleted file mode 100644 index 2f47e97cd2..0000000000 --- a/modules/fts/pages/fts-queryshape-multipolygon.adoc +++ /dev/null @@ -1,514 +0,0 @@ -= MultiPolygon Query - -[abstract] -A GeoJSON MultiPolygon Query against any GeoJSON type. - -== QueryShape for a MultiPolygon Query - -A GeoJSON query via a GeoShape of MultiPolygon to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within. - -=== MultiPolygon `Intersects` Query - -An `intersect` query for multipolygon returns all the matched documents with shapes that overlap with the area of any of the polygons within the query. - -A multipolygon `intersection` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "MultiPolygon", - "coordinates": [ - [ - [[-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399]] - ], - [ - [[-109.05029296875,37.00255267215955], - [-102.041015625,37.00255267215955], - [-102.041015625,40.9964840143779], - [-109.05029296875,40.9964840143779], - [-109.05029296875,37.00255267215955]] - ] - ] - }, - "relation": "intersects" - } - } -} ----- - -The intersection rules are similar to that of the Polygon Query shape described earlier. -The rules will be applied to every indexed GeoJSON Polygon shape in the MultiPolygon array. -If any of the query polygons intersect, then it will be a matching document. - -=== MultiPolygon `Contains` Query - -A `contains` query for multipolygon returns all the matched documents with shape(s) that collectively contain the area of every polygon within the query. - -A multipolygon `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [ - [[-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399]] - ], - [ - [[-109.05029296875,37.00255267215955], - [-102.041015625,37.00255267215955], - [-102.041015625,40.9964840143779], - [-109.05029296875,40.9964840143779], - [-109.05029296875,37.00255267215955]] - ] - ] - }, - "relation": "contains" - } - } -} ----- - -The containment rules are similar to that of the Polygon Query shape described earlier. -The rules will be applied to every indexed GeoJSON Polygon shape in the MultiPolygon array. -If every query polygon is contained within any of the indexed shapes in the document, then it will be considered as a matching document. - -=== MultiPolygon `WithIn` Query - -The Within query is not supported by line geometries. - -A `within` query for multipolygon returns all the matched documents with shape(s) that are residing within the area of any of the polygons within the query. - -A multipolygon `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [ - [[-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399]] - ], - [ - [[-109.05029296875,37.00255267215955], - [-102.041015625,37.00255267215955], - [-102.041015625,40.9964840143779], - [-109.05029296875,40.9964840143779], - [-109.05029296875,37.00255267215955]] - ] - ] - }, - "relation": "within" - } - } -} ----- - -WithIn rules for the MultiPolygon Query with other indexed GeoJSON shapes in the document set are given below. - -The within rules are similar to that of the Polygon Query shape described earlier. -The rules will be applied to every indexed GeoJSON Polygon shape in the MultiPolygon array. -If all the polygons in the query collectively contain/cover all of the shapes in the documents, then it will be considered as a matching document. - -== Example MultiPolygon Query (against Points) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Matches when the multipolygon in the query contains the point in the document including points on the edge or coinciding with the vertices of the multipolygon. - -The MultiPolygon contains a two polygons one for Utah and one for Colorado. The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geojson", - "geometry": { - "shape": { - "type": "MultiPolygon", - "coordinates": [ - [ - [[-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399]] - ], - [ - [[-109.05029296875,37.00255267215955], - [-102.041015625,37.00255267215955], - [-102.041015625,40.9964840143779], - [-109.05029296875,40.9964840143779], - [-109.05029296875,37.00255267215955]] - ] - ] - }, - "relation": "within" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of five (5) hits (from a total of 45 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "MultiPolygon", - "coordinates": [ - [ - [ - [ - -114.027099609375, - 42.00848901572399 - ], - [ - -114.04907226562499, - 36.99377838872517 - ], - [ - -109.05029296875, - 36.99377838872517 - ], - [ - -109.05029296875, - 40.98819156349393 - ], - [ - -111.060791015625, - 40.98819156349393 - ], - [ - -111.02783203125, - 42.00848901572399 - ], - [ - -114.027099609375, - 42.00848901572399 - ] - ] - ], - [ - [ - [ - -109.05029296875, - 37.00255267215955 - ], - [ - -102.041015625, - 37.00255267215955 - ], - [ - -102.041015625, - 40.9964840143779 - ], - [ - -109.05029296875, - 40.9964840143779 - ], - [ - -109.05029296875, - 37.00255267215955 - ] - ] - ] - ] - }, - "relation": "within" - }, - "field": "geojson" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7001", - "score": 0.15727687392401135, - "sort": [ - "Aspen Pitkin County Sardy Field" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_8854", - "score": 0.07715884020494193, - "sort": [ - "Boulder Municipal" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_6999", - "score": 0.0741364322553217, - "sort": [ - "Brigham City" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7857", - "score": 0.15503416574594084, - "sort": [ - "Bryce Canyon" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_3567", - "score": 0.07715884020494193, - "sort": [ - "Buckley Afb" - ] - } - ], - "total_hits": 45, - "max_score": 0.28539049531242594, - "took": 10460443, - "facets": null -} - ----- - -== Example MultiPolygon Query (against Circles) - -include::partial$fts-geoshape-prereq-common.adoc[] - -The MultiPolygon contains a two polygons one for Utah and one for Colorado. Intersects when the query multipolygon intersects the circular region in the document. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geoarea", - "geometry": { - "shape": { - "type": "MultiPolygon", - "coordinates": [ - [ - [[-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399]] - ], - [ - [[-109.05029296875,37.00255267215955], - [-102.041015625,37.00255267215955], - [-102.041015625,40.9964840143779], - [-109.05029296875,40.9964840143779], - [-109.05029296875,37.00255267215955]] - ] - ] - }, - "relation": "intersects" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of five (5) hits (from a total of 49 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "MultiPolygon", - "coordinates": [ - [ - [ - [ - -114.027099609375, - 42.00848901572399 - ], - [ - -114.04907226562499, - 36.99377838872517 - ], - [ - -109.05029296875, - 36.99377838872517 - ], - [ - -109.05029296875, - 40.98819156349393 - ], - [ - -111.060791015625, - 40.98819156349393 - ], - [ - -111.02783203125, - 42.00848901572399 - ], - [ - -114.027099609375, - 42.00848901572399 - ] - ] - ], - [ - [ - [ - -109.05029296875, - 37.00255267215955 - ], - [ - -102.041015625, - 37.00255267215955 - ], - [ - -102.041015625, - 40.9964840143779 - ], - [ - -109.05029296875, - 40.9964840143779 - ], - [ - -109.05029296875, - 37.00255267215955 - ] - ] - ] - ] - }, - "relation": "intersects" - }, - "field": "geoarea" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7001", - "score": 0.10519759431791387, - "sort": [ - "Aspen Pitkin County Sardy Field" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_8854", - "score": 0.050596784242215975, - "sort": [ - "Boulder Municipal" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_6999", - "score": 0.04283511574155623, - "sort": [ - "Brigham City" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7857", - "score": 0.23115574489506296, - "sort": [ - "Bryce Canyon" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_3567", - "score": 0.047931898270349875, - "sort": [ - "Buckley Afb" - ] - } - ], - "total_hits": 49, - "max_score": 0.412412891553119, - "took": 11706695, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-queryshape-point.adoc b/modules/fts/pages/fts-queryshape-point.adoc deleted file mode 100644 index 0710affa78..0000000000 --- a/modules/fts/pages/fts-queryshape-point.adoc +++ /dev/null @@ -1,297 +0,0 @@ -= Point Query - -[abstract] -A GeoJSON Point Query against any GeoJSON type. - -== QueryShape for a Point Query - -A GeoJSON query via a GeoShape of Point to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within. - -=== Point `Intersects` Query - -A point `intersection` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "point", - "coordinates": [1.954764, 50.962097] - }, - "relation": "intersects" - } - } -} ----- - -Intersection rules for the Point Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Intersects (relation) + -Document Shape|{nbsp} + -Point (GeoShape) - -| Point -| Matches when the query point overlaps the point in the document (as point is a non-closed shapes). - -| LineString -| Matches when the query point overlaps any of the line endpoints in the document (as linestring is a non-closed shapes). - -| Polygon -| Matches when the query point lies within the area of the polygon. - -| MultiPoint -| Matches when the query point overlaps with any of the many points in the multipoint array in the document. - -| MultiLineString -| Matches when the query point overlaps with any of the linestring endpoints in the multilinestring array in the document. - -| MultiPolygon -| Matches when the query point lies within the area of any of the polygons in the multipolygon array in the document. - -| GeometryCollection -| Matches when the query point overlaps with any of the heterogeneous (above 6) shapes in the geometrycollection array in the document. - -| Circle -| Matches when the query point lies within the area of the circular region in the document. - -| Envelope -| Matches when the query point lies within the area of the rectangular/bounded box region in the document. - -|=== - -=== Point `Contains` Query - -As the point is a non-closed/single spot there is no difference between `intersects` and `contains` query for this GeoShape. -The guiding rules for the `contains` relation are exactly similar to that `intersects`. - -A point `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "point", - "coordinates": [1.954764, 50.962097] - }, - "relation": "contains" - } - } -} ----- - -== Point `WithIn` Query - -As the point is a non-closed shape, it is not possible for it to contain any larger shapes other than just the point itself. - -A point `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": " << fieldName >> ", - "geometry": { - "shape": { - "type": "point", - "coordinates": [1.954764, 50.962097] - }, - "relation": "within" - } - } -} ----- - -WithIn rules for the Point Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| WithIn (relation) + -Document Shape|{nbsp} + -Point (GeoShape) - -| Point (document shape) -| Matches when the query point is exactly the same point in the document. - -|=== - -== Example Point Query (against Points) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Matches when the query point overlaps the point in the document (as point is a non-closed shapes). - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "fields": ["name"], - "query": { - "field": "geojson", - "geometry": { - "shape": { - "type": "point", - "coordinates": [1.954764, 50.962097] - }, - "relation": "contains" - } - }, - "sort": ["name"] -}' | jq . ----- - -The output of one (1) hit (from a total of 1 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "point", - "coordinates": [ - 1.954764, - 50.962097 - ] - }, - "relation": "contains" - }, - "field": "geojson" - }, - "size": 10, - "from": 0, - "highlight": null, - "fields": [ - "name" - ], - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1254", - "score": 9.234442801897503, - "sort": [ - "Calais Dunkerque" - ], - "fields": { - "name": "Calais Dunkerque" - } - } - ], - "total_hits": 1, - "max_score": 9.234442801897503, - "took": 10557459, - "facets": null -} ----- - -== Example Point Query (against Circles) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Matches when the query point lies within the area of the circular region in the document. - -The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "fields": ["name"], - "query": { - "field": "geoarea", - "geometry": { - "shape": { - "type": "point", - "coordinates": [1.954764, 50.962097] - }, - "relation": "intersects" - } - }, - "sort": ["name"] -}' | jq . ----- - -The output of one (1) hit (from a total of 1 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "point", - "coordinates": [ - 1.954764, - 50.962097 - ] - }, - "relation": "intersects" - }, - "field": "geoarea" - }, - "size": 10, - "from": 0, - "highlight": null, - "fields": [ - "name" - ], - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_1254", - "score": 1.2793982619305806, - "sort": [ - "Calais Dunkerque" - ], - "fields": { - "name": "Calais Dunkerque" - } - } - ], - "total_hits": 1, - "max_score": 1.2793982619305806, - "took": 6334489, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-queryshape-polygon.adoc b/modules/fts/pages/fts-queryshape-polygon.adoc deleted file mode 100644 index 704d9ac0c2..0000000000 --- a/modules/fts/pages/fts-queryshape-polygon.adoc +++ /dev/null @@ -1,523 +0,0 @@ -= Polygon Query - -[abstract] -A GeoJSON Polygon Query against any GeoJSON type. - -== QueryShape for a Polygon Query - -A GeoJSON query via a GeoShape of Polygon to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within. - -=== Polygon `Intersects` Query - -An `intersect` query for polygon returns all the matched documents with shapes that overlap with the area of the polygon within the query. - -A polygon `intersection` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ] - }, - "relation": "intersects" - } - } -} ----- - -Intersection rules for the Polygon Query with other indexed GeoJSON shapes in the document set are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Intersects (relation) + -Document Shape|{nbsp} + -Polygon (GeoShape) - -| Point -| Intersects when the polygon area contains the point in the document. - -| LineString -| Intersects when one of the polygon edges in the query intersects the linestring in the document. - -| Polygon -| Intersects when the polygon area in the query intersects the polygon in the document. - -| MultiPoint -| Intersects when the polygon area contains any of the points in the multipoint array in the document. - -| MultiLineString -| Intersects when the polygon area in the query intersects any of the linestring in the multilinestring array in the document. - -| MultiPolygon -| Intersects when the polygon in the query intersects any of the polygons in the multipolygon array in the document. - -| GeometryCollection -| Matches when the query polygon intersects with any of the heterogeneous (above 6) shapes in the geometrycollection array in the document. - -| Circle -| Intersects when the query polygon intersects the circular region in the document. - -| Envelope -| Intersects when the query polygon intersects the area of the rectangular/bounded box region in the document. - -|=== - -=== Polygon `Contains` Query - -A `contains` query for polygon returns all the matched documents with shapes that contain the polygon within the query. - -A polygon `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ] - }, - "relation": "contains" - } - } -} ----- - -Containment rules for the polygon query with other indexed shapes are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Contains (relation) + -Document Shape|{nbsp} + -Polygon (GeoShape) - -| Point -| NA. Point is a non-closed shape. - -| LineString -| NA. Linestring is a non-closed shape. - -| Polygon -| Contains when the polygon in the query resides completely within the polygon in the document. - -| MultiPoint -| NA. MultiPoint is a non-closed shape. - -| MultiLineString -| NA. MultiLineString is a non-closed shape. - -| MultiPolygon -| Contains when the polygon in the query resides completely within any of the polygons in the multipolygon array in the document. - -| GeometryCollection -| Matches when the query polygon is contained within any of the heterogeneous (above 6) shapes in the geometrycollection array in the document. - -| Circle -| Contains when the query polygon resides completely within the circular region in the document. - -| Envelope -| Contains when the query polygon resides completely within the rectangular/bounded box region in the document. - -|=== - -=== Polygon `WithIn` Query - -The Within query is not supported by line geometries. - -A `within` query for polygon returns all the matched documents with shapes that contain the polygon within the query. - -A polygon `contains` query sample is given below. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ] - }, - "relation": "within" - } - } -} ----- - -WithIn rules for the polygon query with other indexed shapes are given below. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Contains (relation) + -Document Shape|{nbsp} + -Polygon (GeoShape) - -| Point -| Matches when the polygon in the query contains the point in the document including points on the edge or coinciding with the vertices of the polygon. - -| LineString -| Matches when the polygon in the query contains both the endpoints of the linestring in the document. - -| Polygon -| Matches when the polygon in the query contains the polygon in the document completely. - -| MultiPoint -| Matches when the polygon in the query contains every point in the multipoint array in the document. - -| MultiLineString -| Matches when the polygon in the query contains every linestring in the multilinestring array in the document. - -| MultiPolygon -| Matches when the polygon in the query contains every polygon in the multipolygon array in the document completely. - -| GeometryCollection -| Matches when the query polygon contains every heterogeneous (above 6) shapes in the geometrycollection array in the document. - -| Circle -| Matches when the polygon in the query contains the circle in the document completely. - -| Envelope -| Matches when the polygon in the query contains the rectangle/envelope in the document completely. - -|=== - -== Example Polygon Query (against Points) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Matches when the polygon in the query contains the point in the document including points on the edge or coinciding with the vertices of the polygon. - -The Polygon below is Utah. The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geojson", - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ] - }, - "relation": "within" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of five (5) hits (from a total of 18 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [ - [ - -114.027099609375, - 42.00848901572399 - ], - [ - -114.04907226562499, - 36.99377838872517 - ], - [ - -109.05029296875, - 36.99377838872517 - ], - [ - -109.05029296875, - 40.98819156349393 - ], - [ - -111.060791015625, - 40.98819156349393 - ], - [ - -111.02783203125, - 42.00848901572399 - ], - [ - -114.027099609375, - 42.00848901572399 - ] - ] - ] - }, - "relation": "within" - }, - "field": "geojson" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_6999", - "score": 0.13231342774148913, - "sort": [ - "Brigham City" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7857", - "score": 0.27669394470240527, - "sort": [ - "Bryce Canyon" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7074", - "score": 0.13231342774148913, - "sort": [ - "Canyonlands Field" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7583", - "score": 0.13231342774148913, - "sort": [ - "Carbon County Regional-Buck Davis Field" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_3824", - "score": 0.24860341896785076, - "sort": [ - "Cedar City Rgnl" - ] - } - ], - "total_hits": 18, - "max_score": 0.27669394470240527, - "took": 16364364, - "facets": null -} ----- - -== Example Polygon Query (against Circles) - -include::partial$fts-geoshape-prereq-common.adoc[] - -Intersects when the query polygon intersects the circular region in the document. - -The Polygon below is Utah. The results are specified to be sorted on `name`. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as `name`). - -[source, command] ----- -curl -s -XPOST -H "Content-Type: application/json" \ --u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \ --d '{ - "query": { - "field": "geoarea", - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ] - }, - "relation": "intersects" - } - }, - "size": 5, - "from": 0, - "sort": ["name"] -}' | jq . ----- - -The output of five (5) hits (from a total of 20 matching docs) is as follows - -[source, json] ----- -{ - "status": { - "total": 1, - "failed": 0, - "successful": 1 - }, - "request": { - "query": { - "geometry": { - "shape": { - "type": "Polygon", - "coordinates": [ - [ - [ - -114.027099609375, - 42.00848901572399 - ], - [ - -114.04907226562499, - 36.99377838872517 - ], - [ - -109.05029296875, - 36.99377838872517 - ], - [ - -109.05029296875, - 40.98819156349393 - ], - [ - -111.060791015625, - 40.98819156349393 - ], - [ - -111.02783203125, - 42.00848901572399 - ], - [ - -114.027099609375, - 42.00848901572399 - ] - ] - ] - }, - "relation": "intersects" - }, - "field": "geoarea" - }, - "size": 5, - "from": 0, - "highlight": null, - "fields": null, - "facets": null, - "explain": false, - "sort": [ - "name" - ], - "includeLocations": false, - "search_after": null, - "search_before": null - }, - "hits": [ - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_6999", - "score": 0.07521314153068777, - "sort": [ - "Brigham City" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7857", - "score": 0.2608486787753336, - "sort": [ - "Bryce Canyon" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7074", - "score": 0.08184801789845488, - "sort": [ - "Canyonlands Field" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_7583", - "score": 0.08652876583277351, - "sort": [ - "Carbon County Regional-Buck Davis Field" - ] - }, - { - "index": "test_geojson_3397081757afba65_4c1c5584", - "id": "airport_3824", - "score": 0.4282420802218974, - "sort": [ - "Cedar City Rgnl" - ] - } - ], - "total_hits": 20, - "max_score": 0.5252881608935254, - "took": 12509460, - "facets": null -} ----- diff --git a/modules/fts/pages/fts-quickstart-guide.adoc b/modules/fts/pages/fts-quickstart-guide.adoc deleted file mode 100644 index 1661037aee..0000000000 --- a/modules/fts/pages/fts-quickstart-guide.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= Search Service Quick Start Guide -:description: Following appropriate preparations, full text searches can be performed in a number of ways. -:page-aliases: fts:fts-performing-searches.adoc#preparing-for-full-text-searches - -[abstract] -{description} - -[#preparing-for-full-text-searches] - -include::partial$fts-user-prerequisites-common.adoc[] - -== Quick Start via the Classic Editor - -include::partial$fts-creating-indexes-common.adoc[] - -For a more detailed explanation of the available Query options, refer to xref:fts-searching-from-the-UI.adoc[Searching from the UI] - -NOTE: During index creation, in support of most query-types, you can select (or create) and use an _analyzer_. -This is optional: if you do not specify an analyzer, a default analyzer is provided. -Analyzers can be created by means of the Couchbase Web Console, during index creation, as described in xref:fts-creating-indexes.adoc[Creating Search Indexes]. -Their functionality and inner components are described in detail in xref:fts-analyzers.adoc[Understanding Analyzers]. - -[#performing-full-text-searches] -== Methods to Access the Search service - -Search queries (Full Text, Geospatial, Numeric, and other) can be performed with: - -* The Couchbase Web Console. -This UI can also be used to create indexes and analyzers. -Refer to xref:fts-searching-from-the-UI.adoc[Searching from the UI] for information. -* The Couchbase REST API. -Refer to xref:fts-searching-with-curl-http-requests.adoc#Searching-with-the-REST-API-(cURL/HTTP)[Searching with the REST API] for information. -Refer also to xref:rest-api:rest-fts.adoc[Search API] for REST reference details. -* The Couchbase SDK. -This supports several languages, and allows Search queries to be performed with each. -Refer to the SDK's xref:java-sdk:concept-docs:full-text-search-overview.adoc[Java Search Overview] page for information. -Note that the xref:java-sdk:howtos:full-text-searching-with-sdk.adoc[Searching from the Java SDK] page for the _Java_ SDK provides an extensive code-example that demonstrates multiple options for performing searches. -//(Refer to <> below for more information.) -* The {sqlpp} Search functions. -These enable you to perform a full text search as part of a {sqlpp} query. -Refer to xref:n1ql:n1ql-language-reference/searchfun.adoc[Search Functions] for information. - -[#establishing-demonstration-indexes] -== Accessing the Search service via the Java SDK - -The Java SDK code-example provided in xref:java-sdk:howtos:full-text-searching-with-sdk.adoc[Searching from the Java SDK] contains multiple demonstration calls — each featuring a different query-combination — and makes use of three different index-definitions, related to the `travel-sample` bucket: for the code example to run successfully, the three indexes must be appropriately pre-established. -//The definitions are provided in xref:fts-demonstration-indexes.adoc[Demonstration Indexes]. -Instructions on how to use the Couchbase REST API to establish the definitions refer to xref:fts-creating-index-with-rest-api.adoc[Index Creation with REST API]. diff --git a/modules/fts/pages/fts-search-request.adoc b/modules/fts/pages/fts-search-request.adoc deleted file mode 100644 index 983f2e5fc7..0000000000 --- a/modules/fts/pages/fts-search-request.adoc +++ /dev/null @@ -1,983 +0,0 @@ -= Search Request -:page-aliases: fts-queries.adoc , fts-consistency.adoc - -[#Query] -== Query - -Search allows multiple query types to be performed on Full Text Indexes. Each of these query types helps enhance the search and retrievability of the indexed data. - -These capabilities include: - -* Input-text and target-text can be analyzed: this transforms input-text into token-streams, according to different specified criteria, allowing richer and more finely controlled forms of text-matching. -* The fuzziness of a query can be specified, so that the scope of matches can be constrained to a particular level of exactitude. A high degree of fuzziness means that a large number of partial matches may be returned. -* Multiple queries can be specified for simultaneous processing, with one given a higher boost than another, ensuring that its results are returned at the top of the set. -* Regular expressions and wildcards can be used in text-specification for search-input. -* Compound queries can be designed such that an appropriate conjunction or disjunction of the total result-set can be returned. -* Geospatial queries can be used for finding the nearest neighbor or points of interest in a bounded region. - -All the above options, and others, are explained in detail in xref:fts-supported-queries.adoc[Supported Queries] - -[#Consistency] -== Consistency - -A mechanism to ensure that the Full Text Search (FTS) index can obtain the most up-to-date version of the document written to a collection or a bucket. - -The consistency mechanism provides xref:#consistency-vectors[Consistency Vectors] as objects in the search query that ensures FTS index searches all your last data written to the vBucket. - -The search service does not respond to the query until the designated vBucket receives the correct sequence number. - -The search query remains blocked while continuously polling the vBucket for the requested data. Once the sequence number of the data is obtained, the query is executed over the data written to the vBucket. - -When using this consistency mode, the query service will ensure that the indexes are synchronized with the data service before querying. - -=== Workflow to understand Consistency - -. Create an FTS index in Couchbase. -. Write a document to the Couchbase cluster. -. Couchbase returns the associate vector to the app, which needs to issue a query request with the vector. -. The FTS index starts searching the data written to the vBucket. - -In this workflow, it is possible that the document written to the vBucket is not yet indexed. So, when FTS starts searching that document, the most up-to-date document versions are not retrieved, and only the indexed versions are queried. - -Therefore, the Couchbase server provides a consistency mechanism to overcome this issue and ensures that the FTS index can search the most up-to-date document written to the vBucket. - -=== Consistency Level - -The consistency level is a parameter that either takes an empty string indicating the unbounded (not_bounded) consistency or at_plus indicating the bounded consistency. - -==== at_plus - -Executes the query, requiring indexes first to be updated to the timestamp of the last update. - -This implements bounded consistency. The request includes a scan_vector parameter and value, which is used as a lower bound. This can be used to implement read-your-own-writes (RYOW). - -If index-maintenance is running behind, the query waits for it to catch up. - -==== not_bounded - -Executes the query immediately, without requiring any consistency for the query. No timestamp vector is used in the index scan. - -This is the fastest mode, because it avoids the costs of obtaining the vector and waiting for the index to catch up to the vector. - -If index-maintenance is running behind, out-of-date results may be returned. - -[#consistency-vectors] -=== Consistency Vectors - -The consistency vectors supporting the consistency mechanism in Couchbase contain the mapping of the vBucket and sequence number of the data stored in the vBucket. - -For more information about consistency mechanism, see xref:fts-consistency.adoc[Consistency] - -==== Example -[source, JSON] ----- -{ - "ctl": { - "timeout": 10000, - "consistency": { - "vectors": { - "index1": { - "607/205096593892159": 2, - "640/298739127912798": 4 - } - }, - "level": "at_plus" - } - }, - "query": { - "match": "jack", - "field": "name" - } -} ----- - -In the example above, this is the set of consistency vectors. - ----- -"index1": { - "607/205096593892159": 2, - "640/298739127912798": 4 -} ----- - -The query is looking within the FTS index "index1" - for: - -* vbucket 607 (with UUID 205096593892159) to contain sequence number 2 -* vbucket 640 (with UUID 298739127912798) to contain sequence number 4 - -=== Consistency Timeout - -It is the amount of time (in milliseconds) the search service will allow for a query to execute at an index partition level. - -If the query execution surpasses this `timeout` value, the query is canceled. However, at this point if some of the index partitions have responded, you might see partial results, otherwise no results at all. - -[source, JSON] ----- -{ - "ctl": { - "timeout": 10000, - "consistency": { - "vectors": { - "index1": { - "607/205096593892159": 2, - "640/298739127912798": 4 - } - }, - "level": "at_plus" - } - }, - "query": { - "match": "jack", - "field": "name" - } -} ----- - -=== Consistency Results - -Consistency result is the attribute that you can use to set the query result option, such as complete. - -==== Example: -[source, JSON] ----- -{ - "query": {...}, - "ctl": { - "consistency": { - "results": "complete" - } - } -} ----- - -=== The "Complete" option - -The complete option allows you to set the query result as "complete" which indicates that if any of the index partitions are unavailable due to the node not being reachable, the query will display an error in response instead of partial results. - -==== Example -[source, JSON] ----- -{ - "query": {...}, - "ctl": { - "consistency": { - "results": "complete" - } - } -} ----- - - -=== Consistency Tips and Recommendations - -Consistency vectors provide "read your own writes" functionality where the read operation waits for a specific time until the write operation is finished. - -When users know that their queries are complex which require more time in completing the write operations, they can set the timeout value higher than the default timeout of 10 seconds so that consistency can be obtained in the search operations. - -However, if this consistency is not required, the users can optimize their search operations by using the default timeout of 10 seconds. - -==== Example - -[source, JSON] ----- -{ - - "ctl": { - "timeout": 10000, - "consistency": { - "vectors": { - "index1": { - "607/205096593892159": 2, - "640/298739127912798": 4 - } - }, - "level": "at_plus" - } - }, - "query": { - "match": "airport", - "field": "type" - } -} ----- - -[#Sizes-From-Pages] -== Size/From/Pages - -The number of results obtained for a Full Text Search request can be large. Pagination of these results becomes essential for sorting and displaying a subset of these results. - -There are multiple ways to achieve pagination with settings within a search request. Pagination will fetch a deterministic set of results when the results are sorted in a certain fashion. - -Pagination provides the following options: - -=== Size/from or offset/limit - -This pagination settings can be used to obtain a subset of results and works deterministically when combined with a certain sort order. - -Using `size/limit` and `offset/from` would fetch at least `size + from` ordered results from a partition and then return the `size` number of results starting at offset `from`. - -Deep pagination can therefore get pretty expensive when using `size + from` on a sharded index due to each shard having to possibly return large resultsets (at least `size + from`) over the network for merging at the coordinating node before returning the `size` number of results starting at offset `from`. - -The default sort order is based on _score_ (relevance) where the results are ordered from the highest to the lowest score. - -==== Example - -Here's an example query that fetches results from the 11th onwards to the 15th that have been ordered by _score_. - -[source, json] ----- -{ - "query": { - "match": "California", - "field": "state" - }, - "size": 5, - "from": 10 -} ----- - -== Search after/before - -For an efficient pagination, you can use the `search_after/search_before` settings. - -`search_after` is designed to fetch the `size` number of results after the key specified and `search_before` is designed to fetch the `size` number of results before the key specified. - -These settings allow for the client to maintain state while paginating - the sort key of the last result (for search_after) or the first result (for search_before) in the current page. - -Both the attributes accept an array of strings (sort keys) - the length of this array will need to be the same length of the "sort" array within the search request. - -NOTE: You cannot use both `search_after` and `search_before` in the same search request. - -=== Example - -Here are some examples using `search_after/search_before` over sort key "_id" (an internal field that carries the document ID). - -[source, json] ----- -{ - "query": { - "match": "California", - "field": "state" - }, - "sort": ["_id"], - "search_after": ["hotel_10180"], - "size": 3 -} ----- - -[source, json] ----- -{ - "query": { - "match": "California", - "field": "state" - }, - "sort": ["_id"], - "search_before": ["hotel_17595"], - "size": 4 -} ----- - -NOTE: A Full Text Search request that doesn't carry any pagination settings will return the first 10 results (`"size: 10", "from": 0`) ordered by _score_ sequentially from the highest to lowest. - -=== Pagination tips and recommendations - -The pagination of search results can be done using the `from` and `size` parameters in the search request. But as the search gets into deeper pages, it starts consuming more resources. - -To safeguard against any arbitrary higher memory requirements, FTS provides a configurable limit bleveMaxResultWindow (10000 default) on the maximum allowable page offsets. However, bumping this limit to higher levels is not a scalable solution. - -To circumvent this problem, the concept of key set pagination in FTS, is introduced. - -Instead of providing `from` as a number of search results to skip, the user will provide the sort value of a previously seen search result (usually, the last result shown on the current page). The idea is that to show the next page of the results, we just want the top N results of that sort after the last result from the previous page. - -This solution requires a few preconditions be met: - -* The search request must specify a sort order. - -NOTE: The sort order must impose a total order on the results. Without this, any results which share the same sort value might be left out when handling the page navigation boundaries. - -A common solution to this is to always include the document ID as the final sort criteria. - -For example, if you want to sort by [“name”, “-age”], instead of sort by [“name”, “-age”, "_id"]. - -With `search_after`/`search_before` paginations, the heap memory requirement of deeper page searches is made proportional to the requested page size alone. So it reduces the heap memory requirement of deeper page searches significantly down from the offset+from values. -_._ - -[#Sorting] -== Sorting - -The FTS results are returned as objects. FTS query includes options to order the results. - -=== Sorting Result Data - -FTS sorting is sorted by descending order of relevance. It can, however, be customized to sort by different fields, depending on the application. - -On query-completion, _sorting_ allows specified members of the result-set to be displayed prior to others: this facilitates a review of the most significant data. - -Within a JSON query object, the required sort-type is specified by using the `sort` field. - -This takes an array of either _strings_, _objects_, or _numeric_ as its value. - -=== Sorting with Strings - -You can specify the value of the `sort` field as an array of strings. -These can be of three types: - -* _field name_: Specifies the name of a field. -+ -If multiple fields are included in the array, the sorting of documents begins according to their values for the field whose name is first in the array. -+ -If any number of these values are identical, their documents are sorted again, this time according to their values for the field whose name is second; then, if any number of these values are identical, their documents are sorted a third time, this time according to their values for the field whose name is third; and so on. -+ -Any document-field may be specified to hold the value on which sorting is to be based, provided that the field has been indexed in some way, whether dynamically or specifically. -+ -The default sort-order is _ascending_. -If a field-name is prefixed with the `-` character, that field's results are sorted in _descending_ order. - -* `_id`:Refers to the document identifier. -Whenever encountered in the array, causes sorting to occur by document identifer. - -* `_score`: Refers to the score assigned the document in the result-set. -Whenever encountered in the array, causes sorting to occur by score. - -==== Example - ----- -"sort": ["country", "state", "city","-_score"] ----- - -This `sort` statement specifies that results will first be sorted by `country`. - -If some documents are then found to have the same value in their `country` fields, they are re-sorted by `state`. - -Next, if some of these documents are found to have the same value in their `state` fields, they are re-sorted by `city`. - -Finally, if some of these documents are found to have the same value in their `city` fields, they are re-sorted by `score`, in _descending_ order. - -The following JSON query demonstrates how and where the `sort` property can be specified: - -[source,json] ----- -{ - "explain": false, - "fields": [ - "title" - ], - "highlight": {}, - "sort": ["country", "-_score","-_id"], - "query":{ - "query": "beautiful pool" - } -} ----- - -The following example shows how the `sort` field accepts _combinations_ of strings and objects as its value. - -[source,json] ----- -{ - ... - "sort": [ - "country", - { - "by" : "field", - "field" : "reviews.ratings.Overall", - "mode" : "max", - "missing" : "last", - "type": "number" - }, - { - "by" : "field", - "field" : "reviews.ratings.Location", - "mode" : "max", - "missing" : "last", - "type": "number" - }, - "-_score" - ] -} ----- - -=== Sorting with Objects - -Fine-grained control over sort-procedure can be achieved by specifying _objects_ as array-values in the `sort` field. - -Each object can have the following fields: - -* `by`: Sorts results on `id`, `score`, or a specified `field` in the Full Text Index. - -* `field`: Specifies the name of a field on which to sort. -Used only if `field` has been specified as the value for the `by` field; otherwise ignored. - -* `missing`: Specifies the sort-procedure for documents with a missing value in a field specified for sorting. -The value of `missing` can be `first`, in which case results with missing values appear _before_ other results; or `last` (the default), in which case they appear _after_. - -* `mode`: Specifies the search-order for index-fields that contain multiple values (in consequence of arrays or multi-token analyzer-output). -The `default` order is undefined but deterministic, allowing the paging of results from `from (_offset_)`, with reliable ordering. -To sort using the minimum or maximum value, the value of `mode` should be set to either `min` or `max`. - -* `type`: Specifies the type of the search-order field value. -For example, `string` for text fields, `date` for DateTime fields, or `number` for numeric/geo fields. - -To fetch more accurate sort results, we strongly recommend specifying the `type` of the sort fields in the sort section of the search request. - -==== Example - -The example below shows how to specify the object-sort. - -NOTE: The below sample assumes that the `travel-sample` bucket has been loaded, and a default index has been created on it. - -[source, json] ----- -{ - "explain": false, - "fields": [ - "*" - ], - "highlight": {}, - "query": { - "match": "bathrobes", - "field": "reviews.content", - "analyzer": "standard" - }, - "size" : 10, - "sort": [ - { - "by" : "field", - "field" : "reviews.ratings.Overall", - "mode" : "max", - "missing" : "last", - "type": "number" - } - ] -} ----- - -For information on loading sample buckets, see xref:manage:manage-settings/install-sample-buckets.adoc[Sample Buckets]. For instructions on creating a default Full Text Index by means of the Couchbase Web Console, see xref:fts-creating-index-from-UI-classic-editor.adoc[Creating Index from UI]. - -This query sorts search-results based on `reviews.ratings.Overall` — a field that is normally multi-valued because it contains an array of different users' ratings. - -When there are multiple values, the highest `Overall` ratings are used for sorting. - -Hotels with no `Overall` rating are placed at the end. - -The following example shows how the `sort` field accepts _combinations_ of strings and objects as its value. - -[source,json] ----- -{ - - "sort": [ - "country", - { - "by" : "field", - "field" : "reviews.ratings.Overall", - "mode" : "max", - "missing" : "last", - "type": "number" - }, - { - "by" : "field", - "field" : "reviews.ratings.Location", - "mode" : "max", - "missing" : "last", - "type": "number" - }, - "-_score" - ] -} ----- - -=== Sorting with Numeric - -You can specify the value of the `sort` field as a numeric type. You can use the `type` field in the object that you specify with the sort. - -With `type` field, you can specify the type of the search order to numeric, string, or DateTime. - -==== Example - -The example below shows how to specify the object-sort with type field as `number`. - -[source,json] ----- -{ - "explain": false, - "fields": [ - "*" - ], - "highlight": {}, - "query": { - "match": "bathrobes", - "field": "reviews.content", - "analyzer": "standard" - }, - "size" : 10, - "sort": [ - { - "by" : "field", - "field" : "reviews.ratings.Overall", - "mode" : "max", - "missing" : "last", - "type": "number" - } - ] -} ----- - -=== Tips for Sorting with fields - -When you sort results on a field that is not indexed, or when a particular document is missing a value for that field, you will see the following series of Unicode non-printable characters appear in the sort field: - -`\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd` - -The same characters may render differently when using a graphic tool or command line tools like `jq`. - -[source,json] ----- - "sort": [ - "����������", - "hotel_9723", - "_score" - ] ----- - -Check your index definition to confirm that you are indexing all the fields you intend to sort by. You can control the sort behavior for missing attributes using the missing field. - -[#Scoring] -== Scoring - -Search result scoring occurs at a query time. The result of the search request is ordered by *score* (relevance), with the descending sort order unless explicitly set not to do so. - -Couchbase uses a slightly modified version of the standard *tf-idf* algorithm. This deviation is to normalize the score and is based on *tf-idf* algorithm. - -For more details on tf-idf, refer xref:#scoring-td-idf[tf-idf] - -By selecting the `explain score` option within the search request, you can obtain the explanation of how the score was calculated for a result alongside it. - -[#fts_explain_scoring_option_enabled] -image::fts-td-idf-explain-scoring-enabled.png[,850,align=left] - -Search query scores all the qualified documents for relevance and applies relevant filters. - -In a search request, you can set `score` to `none` to disable scoring by. See xref:#scoring-option-none[Score:none] - -=== Example - -The following sample query response shows the *score* field for each document retrieved for the query request: - -[source,json] ----- - "hits": [ - { - "index": "DemoIndex_76059e8b3887351c_4c1c5584", - "id": "hotel_10064", - "score": 10.033205341869529, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - }, - { - "index": "DemoIndex_76059e8b3887351c_4c1c5584", - "id": "hotel_10063", - "score": 10.033205341869529, - "sort": [ - "_score" - ], - "fields": { - "_$c": "hotel" - } - } - ], - "total_hits": 2, - "max_score": 10.033205341869529, - "took": 284614211, - "facets": null -} ----- - -[#scoring-td-idf] -=== tf-idf - -`tf-idf`, a short form of *term frequency-inverse document frequency*, is a numerical statistical value that is used to reflect how important a word is to a document in collection or scope. - -`tf-idf` is used as a weighting factor in a search for information retrieval and text mining. The `tf–idf` value increases proportionally to the number of times a word appears in the document, and it is offset by the number of documents in the collection or scope that contains the word. - -Search engines often use the variations of `tf-idf` weighting scheme as a tool in scoring and ranking a document's relevance for a given query. The tf-idf scoring for a document relevancy is done on the basis of per-partition index, which means that documents across different partitions may have different scores. - -When bleve scores a document, it sums a set of sub scores to reach the final score. The scores across different searches are not directly comparable as the scores are directly dependent on the search criteria. So, changing the search criteria, like terms, boost factor etc. can vary the score. - -The more conjuncts/disjuncts/sub clauses in a query can influence the scoring. Also, the score of a particular search result is not absolute, which means you can only use the score as a comparison to the highest score from the same search result. - -FTS does not provide any predefined range for valid scores. - -In Couchbase application, you get an option to explore the score computations during any search in FTS. - -[#fts_explain_scoring_option] -image::fts-td-idf-explain-scoring.png[,850,align=left] - -On the Search page, you can search for a term in any index. The search result displays the search records along with the option *Explain Scoring* to view the score deriving details for search hits and which are determined by using the `tf-idf` algorithm. - -[#fts_explain_scoring_option_enabled] -image::fts-td-idf-explain-scoring-enabled.png[,850,align=left] - -[#scoring-option-none] -=== Score:none - -You can disable the scoring by setting `score` to `none` in the search request. This is recommended in a situation where scoring (document relevancy) is not needed by the application. - -NOTE: Using `"score": "none"` is expected to boost query performance in certain situations. - -==== Example - -[source, json] ----- -{ - "query": { - "match": "California", - "field": "state" - }, - "score": "none", - "size": 100 -} ----- - -=== Scoring Tips and Recommendations - -For a select term, FTS calculates the relevancy score. So, the documents having a higher relevancy score automatically appear at the top in the result. - -It is often observed that users are using Full-Text Search for the exact match queries with a bit of fuzziness or other search-specific capabilities like geo. - -Text relevancy score does not matter when the user is looking for exact or more targeted searches with many predicates or when the dataset size is small. - -In such a case, FTS unnecessarily uses more resources in calculating the relevancy score. Users can, however, optimize the query performance by skipping the scoring. Users may skip the scoring by passing a “score”: “none” option in the search request. - -==== Example - -[source,json] ----- -{ - - "query": {}, - "score": "none", - "size": 10, - "from": 0 -} ----- - -This improves the search query performance significantly in many cases, especially for composite queries with many child search clauses. - -[#Highlighting] -== Highlighting - -The `Highlight` object indicates whether highlighting was requested. - -The pre-requisite includes term vectors and store options to be enabled at the field level to support Highlighting. - -The highlight object contains the following fields: - -* *style* - (Optional) Specifies the name of the highlighter. For example, "html"or "ansi". - -* *fields* - Specifies an array of field names to which Highlighting is restricted. - -=== Example 1 - -As per the following example, when you search the content in the index, the matched content in the `address` field is highlighted in the search response. - -[source,console] ----- -curl -u username:password -XPOST -H "Content-Type: application/json" \ -http://localhost:8094/api/index/travel-sample-index/query \ --d '{ - "explain": true, - "fields": [ - "*" - ], - "highlight": { - "style":"html", - "fields": ["address"] - }, - "query": { - "query": "address:farm" - } -}' ----- - -==== Result - -[#fts_highlighting_in_address_field] -image::fts-highlighting-in-address-field.png[,520,align=left] - -=== Example 2 - -As per the following example, when you search the content in the index, the matched content in the `description` field is highlighted in the search response. - -[source,console] ----- -curl -u username:password -XPOST -H "Content-Type: application/json" \ -http://localhost:8094/api/index/travel-sample-index/query \ --d '{ - "explain": true, - "fields": [ - "*" - ], - "highlight": { - "style":"html", - "fields": ["description"] - }, - "query": { - "query": "description:complementary breakfast" - } -}' ----- - -==== Result - -[#fts_highlighting_in_description_field] -image::fts-highlighting-in-description-field.png[,520,align=left] - -[#Fields] -== Fields - -You can store specific document fields within FTS and retrieve those as a part of the search results. - -It involves the following two-step process: - -. *Indexing* -+ - -you need to specify the desired fields of the matching documents to be retrieved as a part of the index definition. To do so, select the "store" option checkbox in the field mapping definition for the desired fields. The FTS index will store the original field contents intact (without applying any text analysis) as a part of its internal storage. -+ - -For example, if you want to retrieve the field "description" in the document, then enable the "store" option like below. -+ - -[#fts-type-mappings-child-field] -image::fts-type-mappings-child-field-dialog-complete.png[,460,align=left] -+ - -. *Searching* -+ -you need to specify the fields to be retrieved in the "fields" setting within the search request. This setting takes an array of field names which will be returned as part of the search response. The field names must be specified as strings. While there is no field name pattern matching available, you can use an asterisk ("*") to specify that all stored fields be returned with the response. -+ -For retrieving the contents of the aforementioned "description" field, you may use the following search request. -+ - ----- -curl -XPOST -H "Content-Type: application/json" -uUsername:password http://host:port/api/index/FTS/query -d '{ - "fields": ["description"], - "query": {"field": "queryFieldName", "match": "query text"}, -}' ----- - -[#Facets] - -== Search Facets - -Facets are aggregate information collected on a particular result set. -For any search, the user can collect additional facet information along with it. - -All the facet examples below, are for the query "[.code]``water``" on the beer-sample dataset. -FTS supports the following types of facets: - -[#term-facet] -=== Term Facet - -A term facet counts how many matching documents have a particular term for a specific field. - -NOTE: When building a term facet, use the keyword analyzer. Otherwise, multi-term values get tokenized, and the user gets unexpected results. - -==== Example - -* Term Facet - computes facet on the type field which has two values: `beer` and `brewery`. -+ ----- -curl -X POST -H "Content-Type: application/json" \ -http://localhost:8094/api/index/bix/query -d \ -'{ - "size": 10, - "query": { - "boost": 1, - "query": "water" - }, - "facets": { - "type": { - "size": 5, - "field": "type" - } - } -}' ----- -+ -The result snippet below only shows the facet section for clarity. -Run the curl command to see the HTTP response containing the full results. -+ -[source,json] ----- -"facets": { - "type": { - "field": "type", - "total": 91, - "missing": 0, - "other": 0, - "terms": [ - { - "term": "beer", - "count": 70 - }, - { - "term": "brewery", - "count": 21 - } - ] - } -} ----- - -[#numeric-range-facet] -=== Numeric Range Facet - -A numeric range facet works by the users defining their own buckets (numeric ranges). - -The facet then counts how many of the matching documents fall into a particular bucket for a particular field. - -==== Example - -* Numeric Range Facet - computes facet on the `abv` field with 2 buckets describing `high` (greater than 7) and `low` (less than 7). -+ ----- -curl -X POST -H "Content-Type: application/json" \ -http://localhost:8094/api/index/bix/query -d \ -'{ - "size": 10, - "query": { - "boost": 1, - "query": "water" - }, - "facets": { - "abv": { - "size": 5, - "field": "abv", - "numeric_ranges": [ - { - "name": "high", - "min": 7 - }, - { - "name": "low", - "max": 7 - } - ] - } - } -}' ----- -+ -Results: -+ -[source,json] ----- -facets": { - "abv": { - "field": "abv", - "total": 70, - "missing": 21, - "other": 0, - "numeric_ranges": [ - { - "name": "high", - "min": 7, - "count": 13 - }, - { - "name": "low", - "max": 7, - "count": 57 - } - ] - } -} ----- - -[#date-range-facet] -=== Date Range Facet - -The Date Range facet is same as numeric facet, but on dates instead of numbers. - -Full text search and Bleve expect dates to be in the format specified by https://www.ietf.org/rfc/rfc3339.txt[RFC-3339^], which is a specific profile of ISO-8601 that is more restrictive. - -==== Example - -* Date Range Facet - computes facet on the ‘updated’ field that has 2 values old and new. -+ ----- -curl -XPOST -H "Content-Type: application/json" -uAdministrator:asdasd http://:8094/api/index/bix/query -d '{ -"ctl": {"timeout": 0}, -"from": 0, -"size": 0, -"query": { - "field": "country", - "term": "united" -}, - "facets": { - "types": { - "size": 10, - "field": "updated", - "date_ranges": [ - { - "name": "old", - "end": "2010-08-01" - }, - { - "name": "new", - "start": "2010-08-01" - } -] -} -} -}' ----- -+ -Results -+ -[source,json] ----- - "facets": { - "types": { - "field": "updated", - "total": 954, - "missing": 0, - "other": 0, - "date_ranges": [ - { - "name": "old", - "end": "2010-08-01T00:00:00Z", - "count": 934 - }, - { - "name": "new", - "start": "2010-08-01T00:00:00Z", - "count": 20 - } - ] - } - } ----- - -[#Collections] -== Collections - -Collections field lets the user specify an optional list of collection names. - -This would help the users scope their search request to only those specified collections within a multi-collection index. - -This becomes useful with multi-collection indexes as it can speed up searches, as well as the user can manage the Role Based Access Control more granularly with this option. Ie the search user only needs permissions for the requested collections and not for every other collection indexed within the index. - -In the absence of any collection names, the search request would be treated as a normal search request and would retrieve documents from all the indexed collections within the index. - -[#Includelocations] -== IncludeLocations - -Search is capable of returning the array positions for the search term relative to the whole document hierarchical structure. If the user sets it to true then the search service returns the `array_positions` of the search term occurrences inside the document. The user has to enable the `term_vector` field option for the relevant field during the indexing for fetching the location details during the search time. diff --git a/modules/fts/pages/fts-searching-from-N1QL.adoc b/modules/fts/pages/fts-searching-from-N1QL.adoc deleted file mode 100644 index 24c64a1738..0000000000 --- a/modules/fts/pages/fts-searching-from-N1QL.adoc +++ /dev/null @@ -1,685 +0,0 @@ -= Searching from {sqlpp} - -Search functions enable you to use full text search queries directly within a {sqlpp} query. - -== Prerequisites - -To use any of the search functions, the Search service must be available on the cluster. -It is also recommended, but not required, that you should create suitable full text indexes for the searches that you need to perform. - -[NOTE] --- -The examples in this page all assume that demonstration full text indexes have been created. --- - -=== Authorization - -You do not need credentials for the FTS 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]. - -=== 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. - -If you only need to use the capabilities of a full text search without any {sqlpp} features, consider making use of the Search service directly, through the user interface, the REST API, or an SDK. - -[[search,SEARCH()]] -== SEARCH(`identifier`, `query`[, `options`]) - -=== Description - -This function enables you to use a full text search to filter a result set, or as a join predicate. -It is only allowed in the xref:n1ql-language-reference/where.adoc[WHERE] clause or the xref:n1ql-language-reference/join.adoc[ON] clause. - -If a query contains a SEARCH function, the Query engine analyzes the entire query, including the search specification, to select the best index to use with this search, taking any index hints into account. -The Query engine then passes the search specification over to the Search engine to perform the search. - -[TIP] --- -If no suitable full text index can be selected, or no full text index exists, the Query engine falls back on a Primary index or qualified GSI index to produce document keys, and then fetches the documents. -The Search service then creates a temporary index in memory to perform the search. -This process may be slower than using a suitable full text index. --- - -=== Arguments - -identifier:: -[Required] An expression in the form `__keyspaceAlias__[.__path__]`, consisting of the keyspace or keyspace alias in which to search, followed by the path to a field in which to search, using dot notation. -+ -[NOTE] --- -* The identifier must contain the keyspace or keyspace alias if there is more than one input source in the FROM clause. -If there is only one input source in the FROM clause, and the identifier contains a path, the keyspace or keyspace alias may be omitted. -However, if the path is omitted, the keyspace or keyspace alias is mandatory. - -* When the identifier contains a path, it is used as the default field in the _query_ argument, as long as the _query_ argument is a query string. -If the path is omitted, the default field is set to `{underscore}all`. -If the _query_ argument is a query string which specifies a field, this field takes priority, and the path in the identifier is ignored. -Similarly, if the _query_ argument is a query object, the path is ignored. - -* The path must use Search syntax rather than {sqlpp} syntax; in other words, you cannot specify array locations such as `[*]` or `[3]` in the path. - -* If the keyspace, keyspace alias, or path contains any characters such as `-`, you must surround that part of the identifier with backticks `{backtick}{backtick}`. --- -+ -The _identifier_ argument cannot be replaced by a {sqlpp} query parameter. - -query:: -[Required] The full text search query. -This may be one of the following: -+ -[cols="1a,4a", options="header"] -|=== -| Type -| Description - -| string -| A query string. -For more details, refer to xref:fts:fts-supported-queries-query-string-query.adoc[Query String Query]. - -| object -| The query object within a full text search request. -For more details, refer to xref:fts:fts-supported-queries.adoc[Supported queries]. - -| object -| A complete full text search request, including sort and pagination options, and so on. -For more details, refer to xref:fts:fts-sorting.adoc[Sorting Query Results]. - -[NOTE] -==== -When specifying a complete full text search request with the {sqlpp} SEARCH() function, if the value of the `size` parameter is greater than the maximum number of full text search results, the query ignores the `size` parameter and returns all matching results. - -This is different to the behavior of a complete full text search request in the Search service, where the query returns an error if the value of the `size` parameter is greater than the maximum number of full text search results. -==== -|=== -+ -The _query_ argument may be replaced by a {sqlpp} query parameter, as long as the query parameter resolves to a string or an object. - -options:: -[Optional] A JSON object containing options for the search. -The object may contain the following fields: -+ -[cols="1a,1a,3a", options="header"] -|=== -| Name -| Type -| Description - -| `index` -[Optional] -| string, object -| The `index` field may be a string, containing the name of a full text index in the keyspace. -(This may be a full text index alias, but only if the full text index is in the same keyspace.) -This provides an index hint to the Query engine. -If the full text index does not exist, an error occurs. - -[TIP] --- -You can also provide an index hint to the Query engine with the xref:n1ql-language-reference/hints.adoc#use-index-clause[USE INDEX clause]. -This takes precedence over a hint provided by the `index` field. --- - -''' - -The `index` field may also be an object, containing an example of a full text index mapping. -This is treated as an input to the index mapping. -It overrides the default mapping and is used during index selection and filtering. - -The object must either have a default mapping with no type mapping, or a single type mapping with the default mapping disabled. -For more information, refer to xref:fts:fts-creating-indexes.adoc[Creating Indexes]. - -| `indexUUID` -[Optional] -| string -| A string, containing the UUID of a full text index in the keyspace. -This provides an index hint to the Query engine. -If the full text index cannot be identified, an error occurs. - -You can use the `indexUUID` field alongside the `index` field to help identify a full text index. -The `indexUUID` field and the `index` field must both identify the same full text index. -If they identify different full text indexes, or if either of them does not identify a full text index, an error occurs. - -You can find the UUID of a full text index by viewing the index definition. -You can do this using the xref:fts:fts-creating-index-from-UI-classic-editor.adoc#using-the-index-definition-preview[Index Definition Preview] in the Query Workbench, or the xref:rest-api:rest-fts-indexing.adoc[Index Definition] endpoints provided by the Full Text Search REST API. - -| `out` -[Optional] -| string -| A name given to this full text search operation in this keyspace. -You can use this name to refer to this operation using the <> and <> functions. -If this field is omitted, the name of this full text search operation defaults to `"out"`. - -| (other) -[Optional] -| (any) -| Other fields are ignored by the Query engine and are passed on to the Search engine as options. -The values of these options may be replaced with {sqlpp} query parameters, such as `"analyzer": $analyzer`. -|=== - -+ -The _options_ argument cannot be replaced by a {sqlpp} query parameter, but it may contain {sqlpp} query parameters. - -=== Return Value - -A boolean, representing whether the search query is found within the input path. - -This returns `true` if the search query is found within the input path, or `false` otherwise. - -=== Limitations - -The Query service can select a full text index for efficient search in the following cases: - -* If the SEARCH() function is used in a WHERE clause or in an ANSI JOIN. -The SEARCH() function must be on the leftmost (first) JOIN. -It may be on the outer side of a nested-loop JOIN, or either side of a hash JOIN. -RIGHT OUTER JOINs are rewritten as LEFT OUTER JOINs. - -* If the SEARCH() function is evaluated on the `true` condition in positive cases: for example, `SEARCH(_field_, _query_, _options_)`, `SEARCH(_field_, _query_, _options_) = true`, `SEARCH(_field_, _query_, _options_) IN [true, true, true]`, or a condition including one of these with `AND` or `OR`. - -The Query service cannot select a full text index for efficient search in the following cases: - -* If a USE KEYS hint is present; or if the SEARCH() function is used on the inner side of a nested-loop JOIN, a lookup JOIN or lookup NEST, an index JOIN or index NEST, an UNNEST clause, a subquery expression, a subquery result, or a correlated query. - -* If the SEARCH() function is evaluated on the `false` condition, or in negative cases: for example, `NOT SEARCH(_field_, _query_, _options_)`, `SEARCH(_field_, _query_, _options_) = false`, `SEARCH(_field_, _query_, _options_) != false`, `SEARCH(_field_, _query_, _options_) IN [false, true, 1, "a"]`, or in a condition using the relation operators `<`, `{lt}=`, `>`, `>=`, `BETWEEN`, `NOT`, `LIKE`, or `NOT LIKE`. - -In these cases, the Query service must fetch the documents, and the Search service creates a temporary index in memory to perform the search. -This may affect performance. - -If the SEARCH() function is present for a keyspace, no GSI covering scan is possible on that keyspace. -If more than one FTS or GSI index are used in the plan, IntersectScan or Ordered IntersectScan is performed. -To avoid this, use a USE INDEX hint. - -Order pushdown is possible only if query ORDER BY has only <> on the leftmost keyspace. -Offset and Limit pushdown is possible if the query only has a SEARCH() predicate, using a single search index -- no IntersectScan or OrderIntersectScan. -Group aggregates and projection are not pushed. - -=== Examples - -.Search using a query string -==== -The following queries are equivalent: - -[source,sqlpp] ----- -SELECT META(t1).id -FROM `travel-sample`.inventory.airline AS t1 -WHERE SEARCH(t1.country, "+United +States"); ----- - -[source,sqlpp] ----- -SELECT META(t1).id -FROM `travel-sample`.inventory.airline AS t1 -WHERE SEARCH(t1, "country:\"United States\""); ----- - -.Results -[source,json] ----- -[ - - { - "id": "airline_10" - }, - { - "id": "airline_10123" - }, - { - "id": "airline_10226" - }, - { - "id": "airline_10748" - }, -... -] ----- - -The results are unordered, so they may be returned in a different order each time. -==== - -.Search using a query object -==== -[source,sqlpp] ----- -SELECT t1.name -FROM `travel-sample`.inventory.hotel AS t1 -WHERE SEARCH(t1, { - "match": "bathrobes", - "field": "reviews.content", - "analyzer": "standard" -}); ----- - -.Results -[source,json] ----- -[ - { - "name": "Typoeth Cottage" - }, - { - "name": "Great Orme Lighthouse" - }, - { - "name": "New Road Guest House (B&B)" - }, -... -] ----- - -The results are unordered, so they may be returned in a different order each time. -==== - -.Search using a complete full text search request -==== -[source,sqlpp] ----- -SELECT t1.name -FROM `travel-sample`.inventory.hotel AS t1 -WHERE SEARCH(t1, { - "explain": false, - "fields": [ - "*" - ], - "highlight": {}, - "query": { - "match": "bathrobes", - "field": "reviews.content", - "analyzer": "standard" - }, - "size" : 5, - "sort": [ - { - "by" : "field", - "field" : "reviews.ratings.Overall", - "mode" : "max", - "missing" : "last" - } - ] -}); ----- - -.Results -[source,json] ----- -[ - { - "name": "Waunifor" - }, - { - "name": "Bistro Prego With Rooms" - }, - { - "name": "Thornehill Broome Beach Campground" - }, -... -] ----- - -This query returns 5 results, and the results are ordered, as specified by the search options. -As an alternative, you could limit the number of results and order them using the {sqlpp} xref:n1ql-language-reference/limit.adoc[LIMIT] and xref:n1ql-language-reference/orderby.adoc[ORDER BY] clauses. -==== - -.Search against a full text search index that carries a custom type mapping -==== -[source,sqlpp] ----- -SELECT META(t1).id -FROM `travel-sample`.inventory.hotel AS t1 -WHERE t1.type = "hotel" AND SEARCH(t1.description, "amazing"); ----- - -.Results -[source,json] ----- -[ - { - "id": "hotel_20422" - }, - { - "id": "hotel_22096" - }, - { - "id": "hotel_25243" - }, - { - "id": "hotel_27741" - } -] ----- - -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". - -For more information on defining custom type mappings within the full text search index, refer to xref:fts:fts-type-mappings.adoc[Type Mappings]. -Note that for {sqlpp} queries, only full text search indexes with one type mapping are searchable. -Also the supported type identifiers at the moment are "type_field" and "docid_prefix"; "docid_regexp" isn't supported yet for SEARCH queries via {sqlpp}. -==== - -[[search_meta,SEARCH_META()]] -== SEARCH_META([`identifier`]) - -=== Description - -This function is intended to be used in a query which contains a <> function. -It returns the metadata given by the Search engine for each document found by the <> function. -If there is no <> function in the query, or if a full text index was not used to evaluate the search, the function returns MISSING. - -=== Arguments - -identifier:: -[Optional] An expression in the form `{startsb}__keyspaceAlias__.{endsb}__outname__`, consisting of the keyspace or keyspace alias in which the full text search operation was performed, followed by the outname of the full text search operation, using dot notation. - -[NOTE] --- -* The identifier must contain the keyspace or keyspace alias if there is more than one input source in the FROM clause. -If there is only one input source in the FROM clause, the keyspace or keyspace alias may be omitted. - -* The identifier must contain the outname if there is more than one <> function in the query. -If there is only one <> function in the query, the identifier may be omitted altogether. - -* The outname is specified by the `out` field within the <> function's _options_ argument. -If an outname was not specified by the <> function, the outname defaults to `"out"`. - -* If the keyspace or keyspace alias contains any characters such as `-`, you must surround that part of the identifier with backticks `{backtick}{backtick}`. --- - -=== Return Value - -A JSON object containing the metadata returned by the Search engine. -By default, the metadata includes the score and ID of the search result. -It may also include other metadata requested by advanced search options, such as the location of the search terms or an explanation of the search results. - -=== Examples - -.Select search metadata -==== -[source,sqlpp] ----- -SELECT SEARCH_META() AS meta -- <1> -FROM `travel-sample`.inventory.hotel AS t1 -WHERE SEARCH(t1, { - "query": { - "match": "bathrobes", - "field": "reviews.content", - "analyzer": "standard" - }, - "includeLocations": true -- <2> -}) -LIMIT 3; ----- - -.Result -[source,json] ----- -[ - { - "meta": { - "id": "hotel_12068", // <3> - "locations": { // <4> - "reviews.content": { - "bathrobes": [ - { - "array_positions": [ - 8 - ], - "end": 664, - "pos": 122, - "start": 655 - } - ] - } - }, - "score": 0.3471730605306995 // <5> - } - }, - { - "meta": { - "id": "hotel_18819", - "locations": { - "reviews.content": { - "bathrobes": [ - { - "array_positions": [ - 6 - ], - "end": 110, - "pos": 19, - "start": 101 - } - ] - } - }, - "score": 0.3778486940124847 - } - }, - { - "meta": { - "id": "hotel_5841", - "locations": { - "reviews.content": { - "bathrobes": [ - { - "array_positions": [ - 0 - ], - "end": 1248, - "pos": 242, - "start": 1239 - } - ] - } - }, - "score": 0.3696905918027607 - } - } -] ----- -==== - -<1> There is only one <> function in this query, so the SEARCH_META() function does not need to specify the outname. -<2> The full text search specifies that locations should be included in the search result metadata. -<3> The id is included in the search result metadata by default. -<4> The location of the search term is included in the search result metadata as requested. -<5> The score is included in the search result metadata by default. - -.Select the search metadata by outname -==== -[source,sqlpp] ----- -SELECT t1.name, SEARCH_META(s1) AS meta -- <1> -FROM `travel-sample`.inventory.hotel AS t1 -WHERE SEARCH(t1.description, "mountain", {"out": "s1"}) -- <2> -AND SEARCH(t1, { - "query": { - "match": "bathrobes", - "field": "reviews.content", - "analyzer": "standard" - } -}); ----- - -.Results -[source,json] ----- -[ - { - "name": "Marina del Rey Marriott" - } -] ----- -==== - -<1> This query contains two <> functions. -The outname indicates which metadata we want. -<2> The outname is set by the _options_ argument in this <> function. -This query only uses one data source, so there is no need to specify the keyspace. - -[[search_score,SEARCH_SCORE()]] -== SEARCH_SCORE([`identifier`]) - -=== Description - -This function is intended to be used in a query which contains a <> function. -It returns the score given by the Search engine for each document found by the <> function. -If there is no <> function in the query, or if a full text index was not used to evaluate the search, the function returns MISSING. - -This function is the same as <>. - -=== Arguments - -identifier:: -[Optional] An expression in the form `{startsb}__keyspaceAlias__.{endsb}__outname__`, consisting of the keyspace or keyspace alias in which the full text search operation was performed, followed by the outname of the full text search operation, using dot notation. - -[NOTE] --- -* The identifier must contain the keyspace or keyspace alias if there is more than one input source in the FROM clause. -If there is only one input source in the FROM clause, the keyspace or keyspace alias may be omitted. - -* The identifier must contain the outname if there is more than one <> function in the query. -If there is only one <> function in the query, the identifier may be omitted altogether. - -* The outname is specified by the `out` field within the <> function's _options_ argument. -If an outname was not specified by the <> function, the outname defaults to `"out"`. - -* If the keyspace or keyspace alias contains any characters such as `-`, you must surround that part of the identifier with backticks `{backtick}{backtick}`. --- - -=== Return Value -A number reflecting the score of the result. - -=== Examples - -.Select the search score -==== - -[source,sqlpp] ----- -SELECT name, description, SEARCH_SCORE() AS score -- <1> -FROM `travel-sample`.inventory.hotel AS t1 -WHERE SEARCH(t1.description, "mountain") -ORDER BY score DESC -LIMIT 3; ----- - -.Results -[source,json] ----- -[ - { - "description": "3 Star Hotel next to the Mountain Railway terminus and set in 30 acres of grounds which include Dolbadarn Castle", - "name": "The Royal Victoria Hotel" - }, - { - "description": "370 guest rooms offering both water and mountain view.", - "name": "Marina del Rey Marriott" - }, - { - "description": "This small family run hotel captures the spirit of Mull and is a perfect rural holiday retreat. The mountain and sea blend together to give fantastic, panoramic views from the hotel which is in an elevated position on the shoreline. Panoramic views are also available from the bar and restaurant which serves local produce 7 days a week.", - "name": "The Glenforsa Hotel" - } -] ----- -==== - -<1> There is only one <> function in this query, so the SEARCH_SCORE() function does not need to specify the outname. - -== FTS FLEX (FTS + {sqlpp} Extended Support For Collections) - -FTS is capable of supporting multiple collections within a single index definition. - -Pre Couchbase Server 7.0 index definitions will continue to be supported with 7.0 FTS. - -If the user wants to set up an index definition to subscribe to just a few collections within a single scope, they will be able to do so by toggling the "doc_config.mode" to either of ["scope.collection.type_field", "scope.collection.docid_prefix"]. - -The type mappings will now take the form of either "scope_name.collection_name" (to index all documents within that scope.collection) or "scope_name.collection_name.type_name" (to index only those documents within that scope.collection that match "type" = "type_name") . We will refer to FTS index definitions in this mode as collection-aware FTS indexes. - -NOTE: The type expression check within {sqlpp} queries becomes unnecessary with collection-aware FTS indexes. - -=== Example - -When you set up an FTS index definition to stream from 2 collections: landmark, hotel such as: - ----- -{ - "type": "fulltext-index", - "name": "travel", - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "params": { - "doc_config": { - "mode": "scope.collection.type_field", - "type_field": "type" - }, - "mapping": { - "analysis": {}, - "default_analyzer": "standard", - "default_mapping": { - "dynamic": true, - "enabled": false - }, - "types": { - "inventory.hotel": { - "enabled": true, - "properties": { - "reviews": { - "enabled": true, - "properties": { - "content": { - "enabled": true, - "fields": [ - { - "analyzer": "keyword", - "index": true, - "name": "content", - "type": "text" - } - ] - } - } - } - } - }, - "inventory.landmark": { - "enabled": true, - "properties": { - "content": { - "enabled": true, - "fields": [ - { - "analyzer": "keyword", - "index": true, - "name": "content", - "type": "text" - } - ] - } - } - } - } - } - } -} ----- - -Below are some {sqlpp} queries targeting the above index definition. - ----- -SELECT META().id -FROM `travel-sample`.`inventory`.`landmark` t USE INDEX(USING FTS) -WHERE content LIKE "%travel%"; ----- - ----- -SELECT META().id -FROM `travel-sample`.`inventory`.`hotel` t USE INDEX(USING FTS) -WHERE reviews.content LIKE "%travel%"; ----- - ----- -SELECT META().id -FROM `travel-sample`.`inventory`.`hotel` t USE INDEX(USING FTS) -WHERE content LIKE "%travel%"; ----- diff --git a/modules/fts/pages/fts-searching-from-the-UI.adoc b/modules/fts/pages/fts-searching-from-the-UI.adoc deleted file mode 100644 index 16372237f4..0000000000 --- a/modules/fts/pages/fts-searching-from-the-UI.adoc +++ /dev/null @@ -1,91 +0,0 @@ -[#Searching-from-the-UI] - -= Searching from the UI -:page-aliases: searching-from-the-UI.adoc, fts-searching-from-the-ui.adoc - -[abstract] -Full Text Search can be performed from the Couchbase Web Console. - -include::partial$fts-user-prerequisites-common.adoc[] - -[#fts-quick-start] -== Access the Full Text Search User Interface - -To access the *Full Text Search* screen, left-click on the *Search* tab, in the navigation bar at the left-hand side: - -[#fts_select_search_tab] -image::fts-select-search-tab.png[,100,align=left] - -The *Full Text Search* screen now appears, as follows: - -[#fts_fts_console_initial] -image::fts-search-page.png[,,align=left] - -The console contains areas for the display of _indexes_ and _aliases_: but both are empty, since none has yet been created. - -[#fts_ensure_there_is_an_index] -== Make sure you have a Search index - -If you don't have a Search index already you could create one against `travel-sample` as follows: - -** Creating a *One Field Index* xref:fts-creating-index-from-UI-classic-editor-onefield.adoc[via the UI] or xref:fts-creating-index-from-REST-onefield.adoc[via the REST API]. - -** Creating a *Dynamic Index* xref:fts-creating-index-from-UI-classic-editor-dynamic.adoc[via the UI] or xref:fts-creating-index-from-REST-dynamic.adoc[via the REST API]. - -** Creating a *Geopoint Index* xref:fts-creating-index-from-UI-classic-editor-geopoint.adoc[via the UI] or xref:fts-creating-index-from-REST-geopoint.adoc[via the REST API]. - -The instructions provided will create an index named something like *travel-sample-index*, *test_dynamic*, or *test_geopoint* all indexes will work (the final one will also have the ability to search against geopoints). - -[#Performing-Queries] -== Perform a Query - -To perform a query, simply type a term into the interactive text-field that appears to the left of the *Search* button on the row for the index you have created. -For example, `restaurant`. -Then, left-click on the *Search* button: - -[#fts_ui_search_for_term] -image::fts-ui-search-for-term.png[,400,align=left] - -A *Search Results* page now appears, featuring documents that contain the specified term: - -[#fts_ui_search_results_page] -image::fts-ui-search-results-page.png[,,align=left] - -By left-clicking on any of the displayed document IDs, you bring up a display that features the entire contents of the document. - -== Advanced Query Settings and Other Features in the UI - -On the *Search Results* page, to the immediate right of the *Search* button, at the top of the screen, appears the *show advanced query settings* checkbox. -Check this to display the advanced settings: - -[#fts_advanced_query_settings] -image::fts-advanced-query-settings.png[,,align=left] - -Three interactive text-fields now appear underneath the *Search* panel: *Timeout (msecs)*, *Consistency Level*, and *Consistency Vector*. -Additionally, the *JSON for Query Request* panel displays the submitted query in JSON format. -Note the *show command-line curl example* checkbox, which when checked, adds to the initial JSON display, to form a completed curl command: - -[#fts_ui_curl_exammple] -image::fts-ui-curl-example.png[,,align=left] - -This example can be copied by means of the *Copy to Clipboard* button, pasted (for example) into a standard console-window, and executed against the prompt. -This feature therefore provides a useful means of extending experiments initially performed with the UI into a subsequent console-based, script-based, or program-based context. -(Note, however, that the addition of credentials for authentication are required for execution of the statement outside the context of the current session within Couchbase Web Console. -See xref:fts-searching-with-curl-http-requests.adoc[Searching with the REST API] for an example.) - -Note also the *Show Scoring* checkbox that appears prior to the entries in the *Results for travel-sample-index* panel. -When this is checked, scores for each document in the list are provided. -For example: - -[#fts_ui_query_scores_display] -image::fts-ui-query-scores-display.png[,,align=left] - -Finally, note the *query syntax help* link that now appears under the *Search* interactive text-field: - -[#fts_query_syntax_help_linke] -image::fts-query-syntax-help-link.png[,700,align=left] - -This link takes the user to the documentation on xref:fts-supported-queries.adoc[Supported Queries]. -Such a query can be specified in the *Search* interactive text-field, thereby allowing a search of considerable complexity to be accomplished within Couchbase Web Console. - -NOTE: Any supported query can be executed from the UI, meaning the UI can accept a valid string (query string syntax) or a JSON object conforming to a supported syntax (query or search request). However the result set will only contain document IDs along with the requested fields and scores (if applicable). Any array positions or facets' results will _NOT_ be displayed. diff --git a/modules/fts/pages/fts-searching-full-text-indexes-aliases.adoc b/modules/fts/pages/fts-searching-full-text-indexes-aliases.adoc deleted file mode 100644 index e5d34e197f..0000000000 --- a/modules/fts/pages/fts-searching-full-text-indexes-aliases.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[#searching-full-text-indexes-aliases] -= Searching Full Text Indexes/Aliases - -[abstract] -Full Text indexes, are available under the *Search* tab of the Couchbase Web Console. - -Full Text indexes are special-purpose indexes that contain targets derived from the textual contents of the documents within one or more buckets or collections from the buckets. For more information about different types of indexes, see xref:learn:services-and-indexes/indexes/indexes.adoc[Indexes]. - -You can access the Full Text Indexes from the *Search* tab. Left-click on this to display the *Full Text Search* panel, which contains a tabular presentation of currently existing indexes, with a row for each index. -(See xref:fts-searching-from-the-UI.adoc[Searching from the UI] for a full illustration.) - -On the same *Search* tab, you can create aliases for one or more indexes. So, if you perform the searches on the the aliases, you can get the result not just from one index but from more indexes associated with the aliases. - -To manage an index, left-click on its row. The row expands, as follows: - -[#fts_index_management_ui] -image::fts-index-management-ui.png[,820,align=left] - -To manage alias, left-click on the alias row. The row expands, as follows: - -[#fts_alias_management_ui] -image::fts-alias-management-ui.png[,820,align=left] - -The following buttons are displayed: - -* [.ui]*Search* searches the specified term in the designated index or alias. -* [.ui]*Delete* causes the current index to be deleted. -* [.ui]*Clone* brings up the *Clone Index* screen, which allows a copy of the current index to be modified as appropriate and saved under a new name. -* [.ui]*Edit* brings up the *Edit Index* screen, which allows the index to be modified. Saving modifications cause the index to be rebuilt. -+ -NOTE: Both the [.ui]*Edit Index* and [.ui]*Clone Index* screens are in most respects the same as the [.ui]*Add Index* screen, which was itself described in xref:fts-searching-from-the-UI.adoc[Searching from the UI]. \ No newline at end of file diff --git a/modules/fts/pages/fts-searching-with-curl-http-requests.adoc b/modules/fts/pages/fts-searching-with-curl-http-requests.adoc deleted file mode 100644 index 67a5e07d99..0000000000 --- a/modules/fts/pages/fts-searching-with-curl-http-requests.adoc +++ /dev/null @@ -1,163 +0,0 @@ -[#Searching-with-the-REST-API-(cURL/HTTP)] -= Searching with the REST API (cURL/HTTP) -:page-aliases: fts-searching-with-the-rest-api.adoc - -[abstract] -Full Text Search can be performed using the Couchbase REST API (cURL/HTTP), at the command-line, through the `curl` utility. - -[#performing-a-full-text-search-with-rest-at-the-command-line] -== Performing a Full Text Search with REST at the Command-Line - -The syntactic elements for a `curl`-based Full Text Search can be obtained from the Couchbase Web Console. The console allows searches performed via the UI to be translated dynamically into `curl` examples. - -Of course you need an existing index refer to either xref:fts-creating-index-from-UI-classic-editor.adoc[Classic Editor] or xref:fts-supported-queries-geo-spatial.adoc#creating_a_geospatial_geopoint_index[Creating a Geospatial Index (type geopoint)] to create an index named something like *travel-sample-index* or *test_geopoint* either index will work either index will work (the latter will also have the ability to search against geopoints). - -To demonstrate this, follow the procedures for accessing the Full Text Search screen, within the Couchbase Web Console, and for performing a simple search; as described in xref:fts-searching-from-the-UI.adoc[Searching from the UI]. Then, left-click on the *show advanced query settings* checkbox, at the right-hand side of the *Search* button: - -[#fts_advanced_query_settings] -image::fts-advanced-query-settings.png[,,align=left] - -The *JSON for Query Request* panel displays the submitted query in JSON format. -Note the *show command-line curl example* checkbox. Selecting this checkbox adds to the content of the initial JSON display to form a completed curl command: - -[#fts_ui_curl_exammple] -image::fts-ui-curl-example.png[,,align=left] - -This example can be copied by means of the *Copy to Clipboard* button, pasted into (for example) a standard console-window, and executed against the prompt. -This feature , therefore, provides a useful means of extending experiments initially performed with the UI into a subsequent console-based, script-based, or program-based context. -Note, however, that authentication is required for the call to be successful from any context outside the current Couchbase Web Console session. -Additionally, familiarity with _query strings_ should be acquired for the creation of more complex queries. - -[#using-query-strings] -== Query Strings and Authentication - -A _Query String_ combines standard alphanumeric characters with syntactic elements in order to specify complex queries in ASCII form. -Query Strings can be used for Full Text Searches performed with both the Couchbase Web Console and the REST API. -A detailed description of Query String-format is provided in xref:fts-supported-queries.adoc[Supported Queries]. - -For example, to search for instances of both `nice` and `view`, specify `"+nice +view"` in a search from the Couchbase Web Console: - -[#fts_query_string_query_at_ui] -image::fts-query-string-query-at-ui.png[,640,align=left] - -When the search has returned, check in succession the *show advanced query settings* and *show command-line curl example* checkboxes. -The *JSON for Query Request* now displays the following: - -[#fts_query_string_results_at_ui] -image::fts-query-string-results-at-ui.png[,,align=left] - -Copy the `curl` command displayed by left-clicking on the *Copy to Clipboard* button. -Before attempting to execute the command from the command-line, paste it into a text-editor, and add appropriate authentication-credentials. -For example: - -[source,bourne] ----- -curl -XPOST -H "Content-Type: application/json" \ --u : http://localhost:8094/api/index/test_geopoint/query \ --d '{ - "explain": true, - "fields": [ - "*" - ], - "highlight": {}, - "query": { - "query": "{+nice +view}" - }, - "size": 10, - "from": 0 -}' ----- - -(For detailed information on Couchbase Server _Role-Based Access Control_, see xref:learn:security/authorization-overview.adoc[Authorization].) - -The code can now be copied again and pasted against the command-line, and executed, with the result-set appearing as standard output. - -For additional assistance on Query String composition, left-click on the *full text query syntax help* link that appears under the *Search* interactive text-field when *show advanced query settings* is checked: - -[#fts_query_syntax_help_linke] -image::fts-query-syntax-help-link.png[,640,align=left] - -This link provides access to a xref:query-string-queries.adoc[page] of information on _Query String_ Full Text Search queries. - -[#searching-specifically] -== Searching Specifically - -Searches should always be as specific as possible: this helps to avoid excessive resource-consumption, and the retrieval of unnecessarily large amounts of data. -To facilitate this, the number of _clauses_ that can be returned by a Search Service query is deliberately capped at _1024_: if a larger number of clauses is to be returned by a query, an error is thrown. - -For example, the following query attempts to use the wildcard `*`, to return all data from documents' `reviews.content` field. -The output is piped to the http://stedolan.github.io/jq[jq] program, to enhance readability: - -[source, console] ----- -curl -XPOST -H "Content-Type: application/json" \ --u : http://localhost:8094/api/index/test_geopoint/query \ --d '{ - "explain": true, - "fields": [ - "*" - ], - "highlight": {}, - "query": { - "wildcard": "aa*", - "field": "reviews.content" - }, - "size": 10, - "from": 0 -}' | jq '.' ----- - -Due to the excessive number of clauses that this query would return, an error is thrown. -The error-output (along with the request parameters) is as follows: - -[source, json] ----- -{ - "error": "rest_index: Query, indexName: test_geopoint, err: TooManyClauses over field: `reviews.content` [21579 > maxClauseCount, which is set to 1024]", - "request": { - "explain": true, - "fields": [ - "*" - ], - "from": 0, - "highlight": {}, - "query": { - "field": "reviews.content", - "wildcard": "*" - }, - "size": 10 - }, - "status": "fail" -} ----- - -Therefore, to fix the problem, the wildcard match should be more precisely specified, and the query re-attempted. For example adjusting the *wildcard* specification to *"aapass:[*]"* will result in a query that succeeds. - -[source, console] ----- -curl -XPOST -H "Content-Type: application/json" \ --u : http://localhost:8094/api/index/test_geopoint/query \ --d '{ - "explain": true, - "fields": [ - "*" - ], - "highlight": {}, - "query": { - "wildcard": "aa*", - "field": "reviews.content" - }, - "size": 10, - "from": 0 -}' | jq '.' ----- - -[#further-rest-examples] -== Further REST Examples - -Further examples of using the REST API to conduct Full Text Searches can be found in xref:fts-supported-queries.adoc[Supported Queries]. - -[#list-of-rest-features-supporting-full-text-search] -== List of REST Features Supporting Full Text Search - -The full range of features for Full Text Search, as supported by the Couchbase REST API, is documented as part of the REST API's reference information on the page xref:rest-api:rest-fts.adoc[Full Text Search API]. diff --git a/modules/fts/pages/fts-searching-with-sdk.adoc b/modules/fts/pages/fts-searching-with-sdk.adoc deleted file mode 100644 index 3cf94272af..0000000000 --- a/modules/fts/pages/fts-searching-with-sdk.adoc +++ /dev/null @@ -1,67 +0,0 @@ -= Searching with SDK - -[.column] -=== {empty} -[.content] -Couchbase provides several SDKs to allow applications to access a Couchbase cluster and Mobile SDKs to carry the application to the edge. - - -.Links to various SDK documentation - -[[analyzer_languages_5.5]] -[cols="1,4,4"] -|=== -| SDK | Details | Link - -|C SDK -|The Couchbase C SDK (`libcouchbase`) enables C and C++ programs to access a Couchbase Server cluster. -The C SDK is also commonly used as a core dependency of SDKs written in other languages to provide a common implementation and high performance. -Libcouchbase also contains the `cbc` suite of command line tools. -|xref:3.3@c-sdk:howtos:full-text-searching-with-sdk.adoc[C SDK 3.3] - -| .NET SDK -| The .NET SDK enables you to interact with a Couchbase Server cluster from the .NET Framework using any Common Language Runtime (CLR) language, including C#, F#, and VB.NET. -It offers both a traditional synchronous API and an asynchronous API based on the Task-based Asynchronous Pattern (TAP). -|xref:3.3@dotnet-sdk:howtos:full-text-searching-with-sdk.adoc[.NET SDK 3.3] - -|Go SDK -|The Couchbase Go SDK allows you to connect to a Couchbase Server cluster from Go. -The Go SDK is a native Go library and uses the high-performance `gocbcore` to handle communicating to the cluster over Couchbase's binary protocols. -|xref:2.5@go-sdk:howtos:full-text-searching-with-sdk.adoc[Go SDK 2.5] - -| Java SDK -| The Java SDK forms the cornerstone of our JVM clients. -It allows Java applications to access a Couchbase Server cluster. -The Java SDK offers traditional synchronous APIs and scalable asynchronous APIs to maximize performance. -|xref:3.3@java-sdk:howtos:full-text-searching-with-sdk.adoc[Java SDK 3.3] - -| Kotlin SDK -| Our new Kotlin SDK allows Kotlin applications to access a Couchbase Server cluster. -|xref:1.0@kotlin-sdk:howtos:full-text-search.adoc[Kotlin SDK 1.0] - -|Node.js SDK -|he Node.js SDK allows you to connect to a Couchbase Server cluster from Node.js. -The Node.js SDK is a native Node.js module using the very fast `libcouchbase` library to handle the communication with the cluster over the Couchbase binary protocol. -|xref:4.1@nodejs-sdk:howtos:full-text-searching-with-sdk.adoc[Node.js SDK 4.1] - -|PHP SDK -|The PHP SDK allows you to connect to a Couchbase Server cluster from PHP. -The PHP SDK is a native PHP extension and uses the Couchbase high-performance C library `libcouchbase` to handle the communication to the cluster over Couchbase binary protocols. -|xref:4.0@php-sdk:howtos:full-text-searching-with-sdk.adoc[PHP SDK 4.0] - -|Python SDK -|The Python SDK allows Python applications to access a Couchbase Server cluster. -The Python SDK offers a traditional synchronous API and integration with twisted, gevent, and asyncio. -It depends on the C SDK (`libcouchbase`) and utilizes it for performance and reliability. -|xref:4.0@python-sdk:howtos:full-text-searching-with-sdk.adoc[Python SDK 4.0] - -|Ruby SDK - -|The Ruby SDK allows Ruby applications to access a Couchbase Server cluster. -The Ruby SDK includes high-performance native Ruby extensions to handle communicating to the cluster over Couchbase's binary protocols. -|xref:3.3@ruby-sdk:howtos:full-text-searching-with-sdk.adoc[Ruby SDK 3.3] - -| Scala SDK -| Our new Scala SDK allows Scala applications to access a Couchbase Server cluster. -It offers synchronous, asynchronous, and reactive APIs for flexibility and maximum performance. -|xref:1.3@scala-sdk:howtos:full-text-searching-with-sdk.adoc[Scala SDK 1.3] diff --git a/modules/fts/pages/fts-secure-fts-queries.adoc b/modules/fts/pages/fts-secure-fts-queries.adoc deleted file mode 100644 index cd88b5ae57..0000000000 --- a/modules/fts/pages/fts-secure-fts-queries.adoc +++ /dev/null @@ -1,26 +0,0 @@ -= Searching Securely Using SSL - -To securely query data from the FTS service, the user must follow these steps: - -1. Provide the username and password (-u). -2. Use https protocol. -3. Specify the IP address of the server hosting the FTS service - . -4. Specify the SSL port (18094). - -*Example* - -[source,console] ----- -curl -u username:password -XPOST -H "Content-Type: application/json" \ -https://:18094/api/index/travel-sample-index/query \ --d '{ - "explain": true, - "fields": [" * "], - "highlight": {}, - "query": { - "query": "{ \"+nice +view\" }" - } - }' ----- - -NOTE: Ensure that the SSL ports are enabled in the cluster. \ No newline at end of file diff --git a/modules/fts/pages/fts-supported-queries-analytic-query.adoc b/modules/fts/pages/fts-supported-queries-analytic-query.adoc deleted file mode 100644 index 4294c64503..0000000000 --- a/modules/fts/pages/fts-supported-queries-analytic-query.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= Analytic Queries - -Use an Analytic query to apply an analyzer to your search request. -If you don't provide an analyzer, the Search Service uses the analyzer from the Search index. - -The following queries are Analytic queries: - -* xref:fts-supported-queries-match.adoc[Match] -* xref:fts-supported-queries-match-phrase.adoc[Match Phrase] - -For information on analyzers, see xref:fts-index-analyzers.adoc[Understanding Analyzers]. diff --git a/modules/fts/pages/fts-supported-queries-boolean-field-query.adoc b/modules/fts/pages/fts-supported-queries-boolean-field-query.adoc deleted file mode 100644 index d97517af8d..0000000000 --- a/modules/fts/pages/fts-supported-queries-boolean-field-query.adoc +++ /dev/null @@ -1,20 +0,0 @@ -= Boolean Query - -A _boolean query_ is a combination of conjunction and disjunction queries. -A boolean query takes three lists of queries: - -* `must`: Result documents must satisfy all of these queries. -* `should`: Result documents should satisfy these queries. -* `must not`: Result documents must not satisfy any of these queries. - -[source,json] ----- -{ - "must": { - "conjuncts":[{"field":"reviews.content", "match": "location"}]}, - "must_not": { - "disjuncts": [{"field":"free_breakfast", "bool": false}]}, - "should": { - "disjuncts": [{"field":"free_breakfast", "bool": true}]} -} ----- \ No newline at end of file diff --git a/modules/fts/pages/fts-supported-queries-compound-query.adoc b/modules/fts/pages/fts-supported-queries-compound-query.adoc deleted file mode 100644 index fddf5cb20b..0000000000 --- a/modules/fts/pages/fts-supported-queries-compound-query.adoc +++ /dev/null @@ -1,8 +0,0 @@ -= Compound Queries - -Compound Queries:: Accept multiple queries simultaneously, and return either the _conjunction_ of results from the result-sets, or a _disjunction_. - -The following queries are compound queries: - -* xref:fts-supported-queries-conjuncts-disjuncts.adoc[Conjuncts & Disjuncts] -* xref:fts-supported-queries-boolean-field-query.adoc[Boolean] \ No newline at end of file diff --git a/modules/fts/pages/fts-supported-queries-conjuncts-disjuncts.adoc b/modules/fts/pages/fts-supported-queries-conjuncts-disjuncts.adoc deleted file mode 100644 index e55d6c790b..0000000000 --- a/modules/fts/pages/fts-supported-queries-conjuncts-disjuncts.adoc +++ /dev/null @@ -1,40 +0,0 @@ -= Conjunction & Disjunction Query - -== Conjunction Query (AND) - -A _conjunction_ query contains multiple _child queries_. -Its result documents must satisfy all of the child queries. - -[source,json] ----- -{ - "conjuncts":[ - {"field":"reviews.content", "match": "location"}, - {"field":"free_breakfast", "bool": true} - ] -} ----- - -A demonstration of a conjunction query using the Java SDK can be found in xref:3.2@java-sdk::full-text-searching-with-sdk.adoc[Searching from the SDK]. - -== Disjunction Query (OR) - -A _disjunction_ query contains multiple _child queries_. -Its result documents must satisfy a configurable `min` number of child queries. -By default this `min` is set to 1. -For example, if three child queries — A, B, and C — are specified, a `min` of 1 specifies that the result documents should be those returned uniquely for A (with all returned uniquely for B and C, and all returned commonly for A, B, and C, omitted). - -[source,json] ----- -{ - "disjuncts":[ - {"field":"reviews.content", "match": "location"}, - {"field":"free_breakfast", "bool": true} - ] -} ----- - -A demonstration of a disjunction query using the Java SDK can be found in xref:3.2@java-sdk::full-text-searching-with-sdk.adoc[Searching from the SDK]. - - - diff --git a/modules/fts/pages/fts-supported-queries-date-range.adoc b/modules/fts/pages/fts-supported-queries-date-range.adoc deleted file mode 100644 index 72cd747d3a..0000000000 --- a/modules/fts/pages/fts-supported-queries-date-range.adoc +++ /dev/null @@ -1,23 +0,0 @@ -= Date Range Query - -A _date_range_ query finds documents containing a date value, in the specified field within the specified range. - -Dates should be in the format specified by RFC-3339, which is a specific profile of ISO-8601. - -Define the endpoints using the fields [.param]`start` and [.param]`end`. -You can omit any one endpoint, but not both. - -The [.param]`inclusive_start` and [.param]`inclusive_end` properties in the query JSON control whether or not the endpoints are included or excluded. - -== Example - -[source,json] ----- -{ - "start": "2001-10-09T10:20:30-08:00", - "end": "2016-10-31", - "inclusive_start": false, - "inclusive_end": false, - "field": "review_date" -} ----- \ No newline at end of file diff --git a/modules/fts/pages/fts-supported-queries-fuzzy.adoc b/modules/fts/pages/fts-supported-queries-fuzzy.adoc deleted file mode 100644 index b94e8b37ad..0000000000 --- a/modules/fts/pages/fts-supported-queries-fuzzy.adoc +++ /dev/null @@ -1,24 +0,0 @@ -= Fuzzy Query - -A _fuzzy query_ matches terms within a specified _edit_ (or _Levenshtein_) distance: meaning that terms are considered to match when they are to a specified degree _similar_, rather than _exact_. -A common prefix of a stated length may be also specified as a requirement for matching. - -NOTE: The fuzzy query is a non-analytic query, meaning it won't perform any text analysis on the query text. - -Fuzziness is specified by means of a single integer. -A value of `0` indicates that the terms must be identical. -The maximum value that you can specify is `2`. -For example: - -[source,json] ----- -{ - "term": "interest", - "field": "reviews.content", - "fuzziness": 2 -} ----- - -A demonstration of __Fuzziness__ using the Java SDK, in the context of the _term query_ (see below) can be found in xref:3.2@java-sdk::full-text-searching-with-sdk.adoc[Searching from the SDK]. - -NOTE: Two such queries are specified, with the difference in fuzziness between them resulting in different forms of match, and different sizes of result-sets. diff --git a/modules/fts/pages/fts-supported-queries-geo-bounded-polygon.adoc b/modules/fts/pages/fts-supported-queries-geo-bounded-polygon.adoc deleted file mode 100644 index 49ce835ac3..0000000000 --- a/modules/fts/pages/fts-supported-queries-geo-bounded-polygon.adoc +++ /dev/null @@ -1,71 +0,0 @@ -= Creating a Query: Polygon-Based - -Note that a detailed example for Geopoint index creation and also executing queries can be found at xref:fts-supported-queries-geopoint-spatial.adoc#creating_a_geospatial_geopoint_index[Geopoint Index Creation] and running queries xref:fts-supported-queries-geopoint-spatial.adoc#creating_geopoint_rest_query_radius_based[Geopoint Radius Queries]. - -In addition detailed information on performing queries with the Search REST API can be found in xref:fts-searching-with-curl-http-requests.adoc[Searching with the REST API]; which shows how to use the full `curl` command and how to incorporate query-bodies into your cURL requests. - -The following query-body uses an array, each of whose elements is a string, containing two floating-point numbers; to specify the latitude and longitude of each of the corners of a polygon --; known as _polygon points_. -In each string, the `lat` floating-point value precedes the `lon.` - -Here, the last-specified string in the array is identical to the initial string, thus explicitly closing the box. -However, specifying an explicit closure in this way is optional: the closure will be inferred by the Couchbase Server if not explicitly specified. - -If a target data-location falls within the box, its document is returned. -The results are specified to be sorted on `name` alone. - -[source,json] ----- -{ - "query": { - "field": "geo", - "polygon_points": [ - "37.79393211306212,-122.44234633404847", - "37.77995881733997,-122.43977141339417", - "37.788031092020155,-122.42925715405579", - "37.79026946582319,-122.41149020154114", - "37.79571192027403,-122.40735054016113", - "37.79393211306212,-122.44234633404847" - ] - }, - "sort": [ - "name" - ] -} ----- - -A subset of formatted output might appear as follows: - -[source,json] ----- - . - . - . -"hits": [ - { - "index": "test_geopoint_610cbb5808dfd319_4c1c5584", - "id": "landmark_25944", - "score": 0.23634379439298683, - "sort": [ - "4" - ] - }, - { - "index": "test_geopoint_610cbb5808dfd319_4c1c5584", - "id": "landmark_25681", - "score": 0.31367419004657393, - "sort": [ - "alta" - ] - }, - { - "index": "test_geopoint_610cbb5808dfd319_4c1c5584", - "id": "landmark_25686", - "score": 0.31367419004657393, - "sort": [ - "atherton" - ] - }, - . - . - . ----- diff --git a/modules/fts/pages/fts-supported-queries-geo-bounded-rectangle.adoc b/modules/fts/pages/fts-supported-queries-geo-bounded-rectangle.adoc deleted file mode 100644 index 38b6c5ffdc..0000000000 --- a/modules/fts/pages/fts-supported-queries-geo-bounded-rectangle.adoc +++ /dev/null @@ -1,73 +0,0 @@ -= Creating a Query: Rectangle-Based - -Note that a detailed example for Geopoint index creation and also executing queries can be found at xref:fts-supported-queries-geopoint-spatial.adoc#creating_a_geospatial_geopoint_index[Geopoint Index Creation] and running queries xref:fts-supported-queries-geopoint-spatial.adoc#creating_geopoint_rest_query_radius_based[Geopoint Radius Queries]. - -In addition detailed information on performing queries with the Search REST API can be found in xref:fts-searching-with-curl-http-requests.adoc[Searching with the REST API]; which shows how to use the full `curl` command and how to incorporate query-bodies into your cURL requests. - -In the following query-body, the `top_left` of a rectangle is expressed by means of an array of two floating-point numbers, specifying a longitude of `-2.235143` and a latitude of `53.482358`. -The `bottom_right` is expressed by means of key-value pairs, specifying a longitude of `28.955043` and a latitude of `40.991862`. -The results are specified to be sorted on `name` alone. - -[source,json] ----- -{ - "from": 0, - "size": 10, - "query": { - "top_left": [-2.235143, 53.482358], - "bottom_right": { - "lon": 28.955043, - "lat": 40.991862 - }, - "field": "geo" - }, - "sort": [ - "name" - ] -} ----- - -A subset of formatted output might appear as follows: - -[source,json] ----- - . - . - . -"hits": [ - { - "index": "test_geopoint_610cbb5808dfd319_4c1c5584", - "id": "landmark_16144", - "score": 0.004836809397039384, - "sort": [ - "02" - ] - }, - { - "index": "test_geopoint_610cbb5808dfd319_4c1c5584", - "id": "hotel_9905", - "score": 0.01625607942050202, - "sort": [ - "1" - ] - }, - { - "index": "test_geopoint_610cbb5808dfd319_4c1c5584", - "id": "hotel_16460", - "score": 0.004836809397039384, - "sort": [ - "11" - ] - }, - { - "index": "test_geopoint_610cbb5808dfd319_4c1c5584", - "id": "hotel_21674", - "score": 0.010011952055063241, - "sort": [ - "17" - ] - }, - . - . - . ----- diff --git a/modules/fts/pages/fts-supported-queries-geo-point-distance.adoc b/modules/fts/pages/fts-supported-queries-geo-point-distance.adoc deleted file mode 100644 index 5c6158525a..0000000000 --- a/modules/fts/pages/fts-supported-queries-geo-point-distance.adoc +++ /dev/null @@ -1,82 +0,0 @@ -= Creating a Query: Radius-Based - -Note that a detailed example for Geopoint index creation and also executing queries can be found at xref:fts-supported-queries-geopoint-spatial.adoc#creating_a_geospatial_geopoint_index[Geopoint Index Creation] and running queries xref:fts-supported-queries-geopoint-spatial.adoc#creating_geopoint_rest_query_radius_based[Geopoint Radius Queries]. - -In addition detailed information on performing queries with the Search REST API can be found in xref:fts-searching-with-curl-http-requests.adoc[Searching with the REST API]; which shows how to use the full `curl` command and how to incorporate query-bodies into your cURL requests. - -The following query-body specifies a longitude of `-2.235143` and a latitude of `53.482358`. -The target-field `geo` is specified, as is a `distance` of `100` miles: this is the radius within which target-locations must reside for their documents to be returned. - -[source,json] ----- -{ - "from": 0, - "size": 10, - "query": { - "location": { - "lon": -2.235143, - "lat": 53.482358 - }, - "distance": "100mi", - "field": "geo" - }, - "sort": [ - { - "by": "geo_distance", - "field": "geo", - "unit": "mi", - "location": { - "lon": -2.235143, - "lat": 53.482358 - } - } - ] -} ----- - -The query contains a `sort` object, which specifies that the returned documents should be ordered in terms of their _geo_distance_ from specified `lon` and `lat` coordinates: these values need not be identical to those specified in the `query` object. - -A subset of formatted console output might appear as follows: - -[source,json] ----- - . - . - . -"hits": [ - { - "index": "test_geopoint_610cbb5808dfd319_4c1c5584", - "id": "landmark_17411", - "score": 0.025840756648257503, - "sort": [ - " \u0001?E#9>N\f\"e" - ] - }, - { - "index": "test_geopoint_610cbb5808dfd319_4c1c5584", - "id": "landmark_17409", - "score": 0.025840756648257503, - "sort": [ - " \u0001?O~i*(kD," - ] - }, - { - "index": "test_geopoint_610cbb5808dfd319_4c1c5584", - "id": "landmark_17403", - "score": 0.025840756648257503, - "sort": [ - " \u0001?Sg*|/t\u001f\u0002" - ] - }, - { - "index": "test_geopoint_610cbb5808dfd319_4c1c5584", - "id": "hotel_17413", - "score": 0.025840756648257503, - "sort": [ - " \u0001?U]S\\.e\u0002_" - ] - }, - . - . - . ----- diff --git a/modules/fts/pages/fts-supported-queries-geojson-spatial.adoc b/modules/fts/pages/fts-supported-queries-geojson-spatial.adoc deleted file mode 100644 index 8d0b967642..0000000000 --- a/modules/fts/pages/fts-supported-queries-geojson-spatial.adoc +++ /dev/null @@ -1,1059 +0,0 @@ -= Geospatial GeoJSON Queries - -[abstract] -_GeoJSON_ queries return documents that contain location in either legacy Geopoint format or standard GeoJSON, thus providing more utility than that of legacy point-distance, bounded-rectangle and bounded-polygon against the indexed Geopoint fields. - -include::partial$fts-geojson-intro-common.adoc[] - -[#prerequisites-dataset] - -== Prerequisites - Modify the travel-sample dataset - -The `travel-sample` bucket, provided for test and development, DOES NOT contains any GeoJSON constructs in the documents (only legacy Geopoint information) as such you will need to modify the `travel-sample` data to work with GeoJSON. - -A dataset modification can be easily accomplished via either - -* Adding a new GeoJSON object(s) to your documents. - -* Converting Geopoints to GeoJSON Point types in your documents. - -To run the examples in this documentation the first update method *"Adding a new GeoJSON object(s) to your documents"* is needed. - -* Example documents that have a geo field (airports, hotels or landmarks) such as `airport_1254` in `travel-sample._default._default`: -+ -[source, json] ----- -{ - "airportname": "Calais Dunkerque", - "city": "Calais", - "country": "France", - "faa": "CQF", - "geo": { - "alt": 12, - "lat": 50.962097, - "lon": 1.954764 - }, - "icao": "LFAC", - "id": 1254, - "type": "airport", - "tz": "Europe/Paris" -} ----- - -* *Adding a new GeoJSON object(s) (required for running the examples)* -+ -Using SQL++ (or {sqlpp}) in the Query Workbench we can quickly read the "geo" objects in `travel-sample._default._default` and generate and add a new geojson object to each document. In addition the second statement will add a higher level GeoJSON (Couchbase addition to the spec) object representing a 10 mile radius around each airport (only for type=airport). -+ -[source, n1ql] ----- -UPDATE `travel-sample`._default._default - SET geojson = { "type": "Point", "coordinates": [geo.lon, geo.lat] } - WHERE geo IS NOT null; - -UPDATE `travel-sample`._default._default - SET geoarea = { "coordinates": [geo.lon, geo.lat], "type": "circle", "radius": "10mi"} - WHERE geo IS NOT null AND type="airport"; ----- -+ -After running the above conversion we would get updated documents for airports like (hotels and landmarks will not have a geoarea sub-object): -+ -[source, json] ----- -{ - "airportname": "Calais Dunkerque", - "city": "Calais", - "country": "France", - "faa": "CQF", - "geo": { - "alt": 12, - "lat": 50.962097, - "lon": 1.954764 - }, - "geoarea": { - "coordinates": [ - 1.954764, - 50.962097 - ], - "radius": "10mi", - "type": "circle" - }, - "geojson": { - "coordinates": [ - 1.954764, - 50.962097 - ], - "type": "Point" - }, - "icao": "LFAC", - "id": 1254, - "type": "airport", - "tz": "Europe/Paris" -} ----- - -* *Converting Geopoints (for reference only, do not use for the examples)* -+ -Using SQL++ (or {sqlpp}) in the Query Workbench we can quickly convert all top level "geo" objects in `travel-sample._default._default` -+ -[source, n1ql] ----- -UPDATE `travel-sample`._default._default - SET geo.type = "Point", geo.coordinates = [geo.lon, geo.lat] WHERE geo IS NOT null; - -UPDATE `travel-sample`._default._default - UNSET geo.lat, geo.lon WHERE geo IS NOT null; ----- -+ -After running the above conversion we would get updated documents like: -+ -[source, json] ----- -{ - "airportname": "Calais Dunkerque", - "city": "Calais", - "country": "France", - "faa": "CQF", - "geo": { - "alt": 12, - "coordinates": [ - 1.954764, - 50.962097 - ], - "type": "Point" - }, - "icao": "LFAC", - "id": 1254, - "type": "airport", - "tz": "Europe/Paris" -} ----- - -== GeoJSON Syntax - -As previously discussed the supported GeoJSON shapes in the Search service are: - -* *Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection* - -The search service follows strict GeoJSON syntax for the above seven (7) standard types: - -* GeoJSON position arrays are either [longitude, latitude], or [longitude, latitude, altitude]. - -** `However the Search service only supports [longitude, latitude].` - -* Right-hand rule winding order as per RFC 7946 GeoJSON recommendations - -** LineString and Polygon geometries contain coordinates in an order: lines go in a certain direction, and polygon rings do too. - -** The direction of LineString often reflects the direction of something in real life: a GPS trace will go in the direction of movement, or a street in the direction of allowed traffic flows. - -** Polygon ring order is undefined in GeoJSON, but there’s a useful default to acquire: the right hand rule. Specifically this means that - -*** The exterior ring should be counterclockwise. - -*** Interior rings should be clockwise. - -In addition to the above shapes, Search also supports a two of additional custom shapes (Couchbase specific) to make the spatial approximations easier for users to utilize: - -* *Circle, and Envelope* - -The search service follows its own syntax for the above two (2) custom types (see below). - -== Supported GeoJSON Data Types - -=== Point (https://www.rfc-editor.org/rfc/rfc7946#section-3.1.2[RFC 7946: 3.1.2]) - -The following specifies a GeoJSON Point field in a document: - -[source, json] ----- -{ - "type": "Point", - "coordinates": [75.05687713623047,22.53539059204079] -} ----- - -A point is a single geographic coordinate, such as the location of a building or the current position given by any Geolocation API. -Note : The standard only supports a single way of specifying the coordinates like an array format of longitude followed by latitude. i.e.: [lng, lat]. - -=== Linestring (https://www.rfc-editor.org/rfc/rfc7946#section-3.1.4[RFC 7946: 3.1.4]) - -The following specifies a GeoJSON Linestring field in a document: - -[source, json] ----- -{ - "type": "LineString", - "coordinates": [ -[ 77.01416015625, 23.0797317624497], -[ 78.134765625, 20.385825381874263] - ] -} ----- - -A linestring defined by an array of two or more positions. By specifying only two points, the linestring will represent a straight line. Specifying more than two points creates an arbitrary path. - -=== Polygon (https://www.rfc-editor.org/rfc/rfc7946#section-3.1.6[RFC 7946: 3.1.6]) - -The following specifies a GeoJSON Polygon field in a document: - -[source, json] ----- -{ - "type": "Polygon", - "coordinates": [ [ [ 85.605, 57.207], - [ 86.396, 55.998], - [ 87.033, 56.716], - [ 85.605, 57.207] - ] ] -} ----- - -A polygon is defined by a list of a list of points. The first and last points in each (outer) list must be the same (i.e., the polygon must be closed). And the exterior coordinates have to be in Counter Clockwise Order in a polygon. (CCW) -Polygons with holes are also supported. The holes has to follow Clockwise Order for the boundary vertices. -For Polygons with a single ring, the ring cannot self-intersect -NOTE: The CCW order of vertices is strictly mandated for the geoshapes in Couchbase Server and any violation of this requirement would result in unexpected search results. - -=== MultiPoint (https://www.rfc-editor.org/rfc/rfc7946#section-3.1.3[RFC 7946: 3.1.3]) - -The following specifies a GeoJSON Multipoint field in a document: - -[source, json] ----- -{ - "type": "MultiPoint", - "coordinates": [ - [ -115.8343505859375, 38.45789034424927], - [ -115.81237792968749, 38.19502155795575], - [ -120.80017089843749, 36.54053616262899], - [ -120.67932128906249, 36.33725319397006] - ] -} ----- - -=== MultiLineString (https://www.rfc-editor.org/rfc/rfc7946#section-3.1.5[RFC 7946: 3.1.5]) - -The following specifies a GeoJSON MultiLineString field in a document: - -[source, json] ----- -{ - "type": "MultiLineString", - "coordinates": [ - [ [ -118.31726074, 35.250105158],[ -117.509765624, 35.3756141] ], - [ [ -118.6962890, 34.624167789],[ -118.317260742, 35.03899204] ], - [ [ -117.9492187, 35.146862906], [ -117.6745605, 34.41144164] ] -] -} ----- - -=== MultiPolygon (https://www.rfc-editor.org/rfc/rfc7946#section-3.1.7[RFC 7946: 3.1.7]) - -The following specifies a GeoJSON MultiPolygon field in a document: - -[source, json] ----- -{ - "type": "MultiPolygon", - "coordinates": [ - [ [ [ -73.958, 40.8003 ], [ -73.9498, 40.7968 ], - [ -73.9737, 40.7648 ], [ -73.9814, 40.7681 ], - [ -73.958, 40.8003 ] ] ], - - - [ [ [ -73.958, 40.8003 ], [ -73.9498, 40.7968 ], - [ -73.9737, 40.7648 ], [ -73.958, 40.8003 ] ] ] - ] -} ----- - -=== GeometryCollection (https://www.rfc-editor.org/rfc/rfc7946#section-3.1.8[RFC 7946: 3.1.8]) - -The following specifies a GeoJSON GeometryCollection field in a document: -A GeometryCollection has a member with the name "geometries". The value of "geometries" is an array. Each element of this array is a GeoJSON Geometry object. It is possible for this array to be empty. - -Unlike the other geometry types described above, a GeometryCollection can be a heterogeneous composition of smaller Geometry objects. For example, a Geometry object in the shape of a lowercase roman "i" can be composed of one point and one LineString. -Nested GeometryCollections are invalid. - -[source, json] ----- -{ - "type": "GeometryCollection", - "geometries": [ - { - "type": "MultiPoint", - "coordinates": [ - [ -73.9580, 40.8003 ], - [ -73.9498, 40.7968 ], - [ -73.9737, 40.7648 ], - [ -73.9814, 40.7681 ] - ] - }, - { - "type": "MultiLineString", - "coordinates": [ - [ [ -73.96943, 40.78519 ], [ -73.96082, 40.78095 ] ], - [ [ -73.96415, 40.79229 ], [ -73.95544, 40.78854 ] ], - [ [ -73.97162, 40.78205 ], [ -73.96374, 40.77715 ] ], - [ [ -73.97880, 40.77247 ], [ -73.97036, 40.76811 ] ] - ] - }, - { - "type" : "Polygon", - "coordinates" : [ - [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ], - [ [ 2 , 2 ] , [ 3 , 3 ] , [ 4 , 2 ] , [ 2 , 2 ] ] - ] - } -] -} ----- - -=== Envelope (Couchbase specific extension) - -Envelope type, which consists of coordinates for upper left and lower right points of the shape to represent a bounding rectangle in the format: +++[[minLon, maxLat], [maxLon, minLat]]+++. - -[source, json] ----- -{ - "type": "envelope", - "coordinates": [ - [72.83, 18.979], - [78.508, 17.4555] - ] -} ----- - -=== Circle (Couchbase specific extension) - -If the user wishes to cover a circular region over earth’s surface, then they could use this shape. -A sample circular shape is as below. - -[source, json] ----- -{ - "type": "circle", - "coordinates": [75.05687713623047,22.53539059204079], - "radius": "1000m" -} ----- - -Circle is specified over the center point coordinates along with the radius (or distance). - -Example formats supported for radius are: -"5in" , "5inch" , "7yd" , "7yards", "9ft" , "9feet", "11km", "11kilometers", "3nm" "3nauticalmiles", "13mm" , "13millimeters", "15cm", "15centimeters", "17mi", "17miles" "19m" or "19meters". - -[#specifying-distances] -== Distances - -Multiple unit-types can be used to express the radius (or distance) of the *Circle* type. -These are listed in the table below, with the strings that specify them in REST queries. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Units | Specify with - -| inches -| `in` or `inch` - -| feet -| `ft` or `feet` - -| yards -| `yd` or `yards` - -| miles -| `mi` or `miles` - -| nautical miles -| `nm` or `nauticalmiles` - -| millimeters -| `mm` or `millimeters` - -| centimeters -| `cm` or `centimeters` - -| meters -| `m` or `meters` - -| kilometers -| `km` or `kilometers` - -|=== - -The integer used to specify the number of units must precede the unit-name, with no space left in-between. -For example, _five inches_ can be specified either by the string `"5in"`, or by the string `"5inches"`; while _thirteen nautical miles_ can be specified as either `"13nm"` or `"13nauticalmiles"`. - -If the unit cannot be determined, the entire string is parsed, and the distance is assumed to be in _meters_. - -= Querying the GeoJSON spatial fields - -Search primarily supports three types of spatial querying capability across those heterogeneous types of geoshapes indexed this is accomplished via a JSON Query Structure. - -== Query Structure: - -[source, json] ----- -{ - "query": { - "field": " << fieldName >> ", - "geometry": { - "shape": { - "type": " << shapeDesc >> ", - "coordinates": [[[ ]]] - }, - "relation": " << relation >> " - } - } -} ----- - -The item *fieldName* is the indexed field to apply the Query Structure against. - -The item *shapeDesc* can be any of the 9 types like Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection, Circle and Envelope. - -The item *relation* can be any of the 3 types like intersects , contains and within. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Relation | Result - -| INTERSECTS -| Return all documents whose spatial field intersects the query geometry. - -| CONTAINS -| Return all documents whose spatial field contains the query geometry - -| WITHIN -| Return all documents whose spatial field is within the query geometry. - -|=== - - -== Sample Query Structures - -=== A point `contains` query - -The `contains` query for point returns all the matched documents with shapes that contain the given point in the query. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "point", - "coordinates": [75.05687713623047, 22.53539059204079] - }, - "relation": "contains" - } - } -} ----- - - -=== LineString `intersects` query - -An `intersect` query for linestring returns all the matched documents with shapes that intersects with the linestring in the query. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "linestring", - "coordinates": [ - [77.01416015625, 23.079731762449878], - [78.134765625, 20.385825381874263] - ] - }, - "relation": "intersects" - } - } -} ----- - - -=== Polygon `WithIn` Query - -A `within` query for polygon returns all the matched documents with shapes that are residing completely within the area of the polygon in the query. - -[source, json] ----- -{ - "query": { - "field": "<>", - "geometry": { - "shape": { - "type": "polygon", - "coordinates": [ - [ - [77.59012699127197, 12.959853852513307], - [77.59836673736572, 12.959853852513307], - [77.59836673736572, 12.965541604118611], - [77.59012699127197, 12.965541604118611], - [77.59012699127197, 12.959853852513307] - ] - ] - }, - "relation": "within" - } - } -} ----- - -[#detailed-geojson-examples] - -== Detailed examples for every QueryShape: - -The Sample Query Structures above just introduces some of the basic QueryShapes, the full list below covers the nine (9) unique QueryShapes utilizes each of them to query 1) a set of GeoJSON points and 2) a set of GeoJSON area shapes in this case Circles (but the "area shapes" could be anything): - -* xref:fts-queryshape-point.adoc[Point Query] -* xref:fts-queryshape-linestring.adoc[LineString Query] -* xref:fts-queryshape-polygon.adoc[Polygon Query] -* xref:fts-queryshape-multipoint.adoc[MultiPoint Query] -* xref:fts-queryshape-multilinestring.adoc[MultiLineString Query] -* xref:fts-queryshape-multipolygon.adoc[MultiPolygon Query] -* xref:fts-queryshape-geometrycollection.adoc[GeometryCollection Query] -* xref:fts-queryshape-circle.adoc[Circle Query] -* xref:fts-queryshape-envelope.adoc[Envelope Query] - - -[#creating_a_geojson_index] -== Creating a Geospatial Index (type geojson) - -To be successful, a geospatial GeoJSON query must reference an index that applies the _geojson_ type mapping to the field containing any of the standard types *Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection* plus the extended types of *Circle and Envelope*. - -This can be achieved with Couchbase Web Console, or with the REST endpoints provided for managing xref:rest-api:rest-fts-indexing.adoc[Indexes]. -Detailed instructions for setting up indexes, and specifying type mappings, are provided in xref:fts-creating-indexes.adoc[Creating Indexes]. - -include::partial$fts-creating-geojson-common.adoc[] - -The index once created can also be accessed by means of the Search REST API -see xref:fts-searching-with-curl-http-requests.adoc[Searching with the REST API]. Furthermore the index could have been created in the first place via the Search REST API see xref:fts-creating-index-with-rest-api.adoc[Index Creation with REST API] for more information on using the Search REST API syntax. - -[#creating_geojson_rest_query_radius_based] -== Creating a Query: Radius-Based - -This section and those following, provide examples of the query-bodies required to make geospatial queries with the Couchbase REST API. -Note that more detailed information on performing queries with the Couchbase REST API can be found in xref:fts-searching-with-the-rest-api.adoc[Searching with the REST API]; which shows how to use the full `curl` command and how to incorporate query-bodies into it. - -The following query-body specifies a longitude of `-2.235143` and a latitude of `53.482358`. -The target-field `geo` is specified, as is a `distance` of `100` miles: this is the radius within which target-locations must reside for their documents to be returned. - -[source, json] ----- -{ - "query": { - "geometry": { - "shape": { - "coordinates": [ - -2.235143, - 53.482358 - ], - "type": "circle", - "radius": "100mi" - }, - "relation": "within" - }, - "field": "geojson" - }, - "size": 10, - "from": 0, - "sort": [ - { - "by": "geo_distance", - "field": "geojson", - "unit": "mi", - "location": { - "lon": -2.235143, - "lat": 53.482358 - } - } - ] -} ----- - -The above query contains a `sort` object, which specifies that the returned documents should be ordered in terms of their _geo_distance_ from specified `lon` and `lat` coordinates: these values need not be identical to those specified in the `query` object. - -image::fts-geojson-search_01.png[,550,align=left] -You can cut-n-paste the above Search body definition into the text area that says "search this index..." - -image::fts-geojson-search_02.png[,550,align=left] -Once pasted hit the *Search* button and the UI will show the first 10 hits - -image::fts-geojson-search_03.png[,,align=left] -The console allows searches performed via the UI to be translated dynamically into cURL examples. -To create a cURL command to do this first check *[X] show advanced query settings* and then check *[X] show command-line query example*. - -You should have a cURL command similar to the following: - -[source, console] ----- -curl -XPOST -H "Content-Type: application/json" \ --u : http://192.168.3.150:8094/api/index/test_geojson/query \ --d '{ - "query": { - "geometry": { - "shape": { - "coordinates": [ - -2.235143, - 53.482358 - ], - "type": "circle", - "radius": "100mi" - }, - "relation": "within" - }, - "field": "geojson" - }, - "size": 10, - "from": 0, - "sort": [ - { - "by": "geo_distance", - "field": "geojson", - "unit": "mi", - "location": { - "lon": -2.235143, - "lat": 53.482358 - } - } - ] -}' ----- - -If you copy and then run the above cURL command via the console the response from the Search service will report that there are 847 total_hits but only return the first 10 hits. A subset of formatted console output might appear as follows: - -NOTE: To pretty print the response just pipe the output through the utility http://stedolan.github.io/jq[jq] to enhance readability. - -[source, json] ----- -"hits": [ - { - "index": "test_geojson_690ac8f8179a4a86_4c1c5584", - "id": "landmark_3604", - "score": 0.21532348857041025, - "sort": [ - " \u0001\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f" - ] - }, - { - "index": "test_geojson_690ac8f8179a4a86_4c1c5584", - "id": "landmark_5571", - "score": 0.12120554320433605, - "sort": [ - " \u0001\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f" - ] - }, - { - "index": "test_geojson_690ac8f8179a4a86_4c1c5584", - "id": "landmark_3577", - "score": 0.2153234885704102, - "sort": [ - " \u0001\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f" - ] - }, - { - "index": "test_geojson_690ac8f8179a4a86_4c1c5584", - "id": "hotel_3606", - "score": 0.2153234885704102, - "sort": [ - " \u0001\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f" - ] - }, - { - "index": "test_geojson_690ac8f8179a4a86_4c1c5584", - "id": "landmark_40167", - "score": 0.27197802451106445, - "sort": [ - " \u0001\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f" - ] - }, - { - "index": "test_geojson_690ac8f8179a4a86_4c1c5584", - "id": "landmark_36152", - "score": 0.12120554320433605, - "sort": [ - " \u0001\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f" - ] - }, - { - "index": "test_geojson_690ac8f8179a4a86_4c1c5584", - "id": "landmark_11329", - "score": 0.12120554320433605, - "sort": [ - " \u0001\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f" - ] - }, - { - "index": "test_geojson_690ac8f8179a4a86_4c1c5584", - "id": "hotel_3643", - "score": 0.2153234885704102, - "sort": [ - " \u0001\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f" - ] - }, - { - "index": "test_geojson_690ac8f8179a4a86_4c1c5584", - "id": "landmark_40038", - "score": 0.27197802451106445, - "sort": [ - " \u0001\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f" - ] - }, - { - "index": "test_geojson_690ac8f8179a4a86_4c1c5584", - "id": "airport_565", - "score": 0.12120554320433605, - "sort": [ - " \u0001\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f\u007f" - ] - } -] ----- - - -[#creating_geojson_rest_query_bounding_box_based] -== Creating a Query: Envelope (or Rectangle-Based) - -In the following query-body, the `top_left` of a rectangle is expressed by means of an *Envelope*, specifying +++[[minLon, maxLat], [maxLon, minLat]] = [[-2.235143, 53.482358],[28.955043, 40.991862]]+++ - -The results are specified to be sorted on `name` alone, since only type hotel and landmark have a name the sort will occur on the tokenized values (they analyzer would need to be type keyword to sort on the actual field names). - -[source, json] ----- -{ - "query": { - "geometry": { - "shape": { - "coordinates": [ - [-2.235143, 53.482358], - [28.955043, 40.991862] - ], - "type": "envelope" - }, - "relation": "within" - }, - "field": "geojson" - }, - "sort": ["name"], - "size": 10, - "from": 0 -} ----- - -A subset of formatted output might appear as follows: - -[source, json] ----- -"hits": [ - { - "index": "test_geojson_3dd53eb1ac88768c_4c1c5584", - "id": "landmark_3604", - "score": 0.004703467956838207, - "sort": [ - "ô¿¿ô¿¿ô¿¿" - ] - }, - { - "index": "test_geojson_3dd53eb1ac88768c_4c1c5584", - "id": "landmark_6067", - "score": 0.004703467956838207, - "sort": [ - "ô¿¿ô¿¿ô¿¿" - ] - }, - { - "index": "test_geojson_3dd53eb1ac88768c_4c1c5584", - "id": "landmark_16320", - "score": 0.004703467956838207, - "sort": [ - "ô¿¿ô¿¿ô¿¿" - ] - }, ----- - -If we added two (2) more child field into the Index definition as follows where both items are searchable as "name" - -image::fts-geojson-mod-index.png[,550,align=left] - -The sort would be on the actual airportname and name fields and the query itself would return these values. - -[source, json] ----- -"hits": [ - { - "index": "test_geojson_4391b0a68d5cc865_4c1c5584", - "id": "hotel_1364", - "score": 0.05896334942635901, - "sort": [ - "'La Mirande Hotel" - ] - }, - { - "index": "test_geojson_4391b0a68d5cc865_4c1c5584", - "id": "landmark_16144", - "score": 0.004703467956838207, - "sort": [ - "02 Shepherd's Bush Empire" - ] - }, - { - "index": "test_geojson_4391b0a68d5cc865_4c1c5584", - "id": "landmark_16181", - "score": 0.004703467956838207, - "sort": [ - "2 Willow Road" - ] - }, - { - "index": "test_geojson_4391b0a68d5cc865_4c1c5584", - "id": "landmark_16079", - "score": 0.004703467956838207, - "sort": [ - "20 Fenchurch Street" - ] - }, ----- - - -[#creating_geojson_rest_query_polygon_based] -== Creating a Query: Polygon-Based - -The following query-body uses an array, each of whose elements is a string, containing multiple floating-point number pairs; to specify the longitude and latitude of each of the lon/lat pairs of a polygon — known as _polygon points_. -In all cases, the `lon` floating-point value precedes the `lat` for the correct GeoJSON winding. - -Here, the last-specified pair in the array is identical to the initial pair, thus explicitly closing the polygon. -However, specifying an explicit closure in this way is optional: closure will be inferred by Couchbase Server if not explicitly specified. - -If a target data-location falls within the polygon, its document is returned. - -Request the first 10 items within the state of Utah (note the query body consists of simple set of hand drawn set of corner points). -The target-field `geojson` is specified, to be compared to the query Polygon the target-locations must reside for their documents to be returned. -Don't worry about newlines when you paste the text. - -The results are specified to be sorted on `name` alone, since only type hotel and landmark have a name the sort will occur on the tokenized values (they analyzer would need to be type keyword to sort on the actual field names). - - -[source, json] ----- -{ - "query": { - "geometry": { - "shape": { - "coordinates": [ - [ - [-114.027099609375, 42.00848901572399], - [-114.04907226562499, 36.99377838872517], - [-109.05029296875, 36.99377838872517], - [-109.05029296875, 40.98819156349393], - [-111.060791015625, 40.98819156349393], - [-111.02783203125, 42.00848901572399], - [-114.027099609375, 42.00848901572399] - ] - ], - "type": "Polygon" - }, - "relation": "within" - }, - "field": "geojson" - }, - "size": 10, - "from": 0, - "sort": ["name"] -} ----- - -A subset of formatted output might appear as follows: - -[source,json] ----- -"hits": [ - { - "index": "test_geojson_4330cb585620d5e8_4c1c5584", - "id": "airport_7857", - "score": 0.27669394470240527, - "sort": [ - "ô¿¿ô¿¿ô¿¿" - ] - }, - { - "index": "test_geojson_4330cb585620d5e8_4c1c5584", - "id": "airport_7581", - "score": 0.13231342774148913, - "sort": [ - "ô¿¿ô¿¿ô¿¿" - ] - }, - { - "index": "test_geojson_4330cb585620d5e8_4c1c5584", - "id": "airport_7727", - "score": 0.27669394470240527, - "sort": [ - "ô¿¿ô¿¿ô¿¿" - ] - }, - { - "index": "test_geojson_4330cb585620d5e8_4c1c5584", - "id": "airport_9279", - "score": 0.27669394470240527, - "sort": [ - "ô¿¿ô¿¿ô¿¿" - ] - }, ----- - -Again if we added two (2) more child field into the Index definition as follows where both items are searchable as "name" - -image::fts-geojson-mod-index.png[,550,align=left] - -The sort would be on the actual airportname and name fields (but there are only airports returned) and the query itself would return these values. - -[source, json] ----- -"hits": [ - { - "index": "test_geojson_4391b0a68d5cc865_4c1c5584", - "id": "airport_6999", - "score": 0.13231342774148913, - "sort": [ - "Brigham City" - ] - }, - { - "index": "test_geojson_4391b0a68d5cc865_4c1c5584", - "id": "airport_7857", - "score": 0.27669394470240527, - "sort": [ - "Bryce Canyon" - ] - }, - { - "index": "test_geojson_4391b0a68d5cc865_4c1c5584", - "id": "airport_7074", - "score": 0.13231342774148913, - "sort": [ - "Canyonlands Field" - ] - }, ----- - -This example quickly creates the same index as xref:fts-creating-index-from-REST-geojson.adoc[Creating a GeoJSON Index via the REST API]. Note it has the two (2) additional child field definitions to allow keyword sorting. - -[#final-geojson-index] - -== Final GeoJSON Search index - -Note, for the samples above that return actual airportname and name fields and also the nine (9) QueryShape examples referenced in <> - -the Search index used is as follows: - -[source, json] ----- -{ - "type": "fulltext-index", - "name": "test_geojson", - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "planParams": { - "maxPartitionsPerPIndex": 1024, - "indexPartitions": 1 - }, - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "", - "mode": "scope.collection.type_field", - "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": { - "_default._default": { - "dynamic": true, - "enabled": true, - "properties": { - "airportname": { - "dynamic": false, - "enabled": true, - "fields": [ - { - "analyzer": "keyword", - "include_in_all": true, - "index": true, - "name": "name", - "store": true, - "type": "text" - } - ] - }, - "geoarea": { - "dynamic": false, - "enabled": true, - "fields": [ - { - "include_in_all": true, - "index": true, - "name": "geoarea", - "type": "geoshape" - } - ] - }, - "geojson": { - "dynamic": false, - "enabled": true, - "fields": [ - { - "include_in_all": true, - "index": true, - "name": "geojson", - "type": "geoshape" - } - ] - }, - "name": { - "dynamic": false, - "enabled": true, - "fields": [ - { - "analyzer": "keyword", - "include_in_all": true, - "index": true, - "name": "name", - "store": true, - "type": "text" - } - ] - } - } - } - } - }, - "store": { - "indexType": "scorch", - "segmentVersion": 15 - } - }, - "sourceParams": {} -} ----- - -If viewed in the UI: - -image::fts-geojson-mod-index-full.png[,600,align=left] diff --git a/modules/fts/pages/fts-supported-queries-geopoint-spatial.adoc b/modules/fts/pages/fts-supported-queries-geopoint-spatial.adoc deleted file mode 100644 index 075cfd5bb1..0000000000 --- a/modules/fts/pages/fts-supported-queries-geopoint-spatial.adoc +++ /dev/null @@ -1,585 +0,0 @@ -= Geospatial Geopoint Queries -:page-aliases: fts-supported-queries-geo-spatial.adoc - -[abstract] -_Geospatial_ geopoint queries return documents that contain location. Each document specifies a geographical location. - -A _geospatial geopoint query_ specifies an area and returns each document that contains a reference to a location within the area. -Areas and locations are represented by _latitude_-_longitude_ coordinate pairs. - -The location data provided by a geospatial geopoint query can be any of the following: - -* A location, is specified as a longitude-latitude coordinate pair; and a distance. -The location determines the center of a circle whose radius-length is the specified distance. -Documents are returned if they reference a location within the circle. For details of the units and formats in which distances can be specified, see xref:fts:fts-supported-queries-geo-spatial.adoc#specifying-distances[Specifying Distances]. - -* Two latitude-longitude coordinate pairs. -These are respectively taken to indicate the top left and bottom right corners of a _rectangle_. -Documents are returned if they reference a location within the area of the rectangle. - -* An array of three or more latitude-longitude coordinate pairs. -Each of the pairs is taken to indicate one corner of a _polygon_. -Documents are returned if they reference a location within the area of the polygon. - -A geospatial geopoint query must be applied to an index that uses the _geopoint_ type mapping to the document-field that contains the target longitude-latitude coordinate pair. - -To be successful, a geospatial geopoint query must reference an index within which the _geopoint_ type mapping has been applied to the field containing the target latitude-longitude coordinate pair. - -Geospatial queries return _all_ documents whose locations are within the query-specified area. -To specify _holes_ within the area so that one or more subsets of returned documents can be omitted from the final results, boolean queries should be applied to the set of documents returned by the geospatial geopoint query. -See xref:fts-supported-queries.adoc[Supported Queries]. - -Latitude-longitude coordinate pairs can be specified in multiple ways, including as _geohashes_; as demonstrated in xref:fts:fts-supported-queries-geo-spatial.adoc#specifying-coordinates[Specifying Coordinates], below. - -[#recognizing_target_data] -== Recognizing Target Data - -The `travel-sample` bucket, provided for test and development, contains multiple documents that specify locations. -For example, those that represent airports, such as `airport_1254`: - -[source, json] ----- -{ - "airportname": "Calais Dunkerque", - "city": "Calais", - "country": "France", - "faa": "CQF", - "geo": { - "alt": 12, - "lat": 50.962097, - "lon": 1.954764 - }, - "icao": "LFAC", - "id": 1254, - "type": "airport", - "tz": "Europe/Paris" -} ----- - -The `geo` field contains the `lon` and `lat` key-value pairs. -Note that the `geo` field needs to contain the longitude-latitude information in the form of a string (comma separated numeric content or a hash), array, or object. - -* String syntax: `"lat,lon"`, `"geohash"` -* Array syntax: `[lon, lat]` (where lon and lat are both floating point integers) -* Object syntax: `{"lon" : 0.0, "lat": 0.0}`, `{"lng": 0.0, "lat": 0.0}` (note that these are the only accepted field names for longitude and latitude) - -Moreover, any other child-fields, such as `alt` (in the above example) - are ignored. - -For information on installing the `travel-sample` bucket, see xref:manage:manage-settings/install-sample-buckets.adoc[Sample Buckets]. - -[#specifying-coordinates] -=== Specifying Coordinates - -Each latitude-longitude coordinate can be expressed by means of any of the following. - -[#two-key-value-pairs] -==== Two Key-Value Pairs - -An individual latitude-longitude coordinate can be expressed by means of an object containing two key-value pairs. -For example, the central location for a radius-based area can be expressed as follows: - -[source, json] ----- -"location": { - "lon": -2.235143, - "lat": 53.482358 - } ----- - -Where multiple coordinates are required, for the specifying of a polygon, an array of such objects can be specified, as follows: - -[source, json] ----- -"polygon_points": [ - { “lat”: 37.79393211306212, “lon”: -122.44234633404847 }, - { “lat”: 37.77995881733997, “lon”: -122.43977141339417 }, - { “lat”: 37.788031092020155, “lon”: -122.4292571540557 }, - { “lat”: 37.79026946582319, “lon”: -122.41149020154114 }, - { “lat”: 37.79571192027403, “lon”: -122.40735054016113 }, - { “lat”: 37.79393211306212, “lon”: -122.44234633404847 } -] ----- - -[#a-string-containing-two-floating-point-numbers] -==== A String, Containing Two Floating-Point Numbers - -An individual latitude-longitude coordinate can be expressed as a string containing two floating-point numbers — the first signifying latitude, the second longitude. -For example, the center of a circle can be specified as follows: - -[source, json] ----- -"location": "53.482358,-2.235143" ----- - -Where multiple coordinates are required, for the specifying of a polygon, an array of such strings can be specified, as follows: - -[source, json] ----- -"polygon_points": [ - "37.79393211306212,-122.44234633404847", - "37.77995881733997,-122.43977141339417", - "37.788031092020155,-122.42925715405579", - "37.79026946582319,-122.41149020154114", - "37.79571192027403,-122.40735054016113", - "37.79393211306212,-122.44234633404847" -] ----- - -[#an-array-of-floating-point-numbers] -==== An Array of Two Floating-Point Numbers - -An individual latitude-longitude coordinate can be expressed as an array of two floating-point numbers — the first signifying longitude, the second latitude. -For example, the top left corner of a rectangle can be specified as follows: - -[source,javascript] ----- -"top_left": [ -2.235143, 53.482358 ] ----- - -Where multiple coordinates are required, for the specifying of a polygon, an array of such arrays can be specified, as follows: - -[source, json] ----- -"polygon_points": [ - [ -122.44234633404847, 37.79393211306212 ], - [ -122.43977141339417, 37.77995881733997 ], - [ -122.42925715405579, 37.78803109202015 ], - [ -122.41149020154114, 37.79026946582319 ], - [ -122.40735054016113, 37.79571192027403 ], - [ -122.44234633404847, 37.79393211306212 ] -] ----- - -[#a-geohash] -==== A Geohash - -A latitude-longitude coordinate can be expressed by means of a single https://en.wikipedia.org/wiki/Geohash[Geohash] encoding. -For example, the bottom right corner of a rectangle can be specified as follows: - -[source, json] ----- -"bottom_right": "gcw2m0hmm6hs" ----- - -Where multiple coordinates are required, for the specifying of a polygon, an array of geohashes can be specified, as follows: - -[source, json] ----- -"polygon_points": [ - “9q8zjbkp”, - “9q8yvvdh”, - “9q8yyp1e”, - “9q8yyrw8”, - “9q8zn83x”, - “9q8zjb0j” -] ----- - -Means of latitude-longitude conversion to and from this format are provided at http://geohash.co/[Geohash Converter]. -Additional information, including on the _precision_ of values specified in this format, is provided at https://www.movable-type.co.uk/scripts/geohash.html[Movable Type Scripts — Geohashes]. - -[#specifying-distances] -=== Specifying Distances - -Multiple unit-types can be used to express distance. -These are listed in the table below, with the strings that specify them in REST queries. - -[#geospatial-distance-units,cols="1,2"] -|=== -| Units | Specify with - -| inches -| `in` or `inch` - -| feet -| `ft` or `feet` - -| yards -| `yd` or `yards` - -| miles -| `mi` or `miles` - -| nautical miles -| `nm` or `nauticalmiles` - -| millimeters -| `mm` or `millimeters` - -| centimeters -| `cm` or `centimeters` - -| meters -| `m` or `meters` - -| kilometers -| `km` or `kilometers` - -|=== - -The integer used to specify the number of units must precede the unit-name, with no space left in-between. -For example, _five inches_ can be specified either by the string `"5in"`, or by the string `"5inches"`; while _thirteen nautical miles_ can be specified as either `"13nm"` or `"13nauticalmiles"`. - -If the unit cannot be determined, the entire string is parsed, and the distance is assumed to be in _meters_. - -[#creating_a_geospatial_index] -[#creating_a_geospatial_geopoint_index] -== Creating a Geospatial Index (type geopoint) - -To be successful, a geospatial geopoint query must reference an index that applies the _geopoint_ type mapping to the field containing the latitude-longitude coordinate pair. -This can be achieved with Couchbase Web Console, or with the REST endpoints provided for managing xref:rest-api:rest-fts-indexing.adoc[Indexes]. -Detailed instructions for setting up indexes, and specifying type mappings, are provided in xref:fts-creating-indexes.adoc[Creating Indexes]. - -For initial experimentation with geospatial geopoint querying (based on the type geopoint), the `geo` field of documents within the `travel-sample` bucket can be specified as a child field of the `default` type mapping (keyspace `travel-sample._default._default` as follows: - -include::partial$fts-creating-geopoint-common.adoc[] - -The index once created can also be accessed by means of the Search REST API -see xref:fts-searching-with-curl-http-requests.adoc[Searching with the REST API]. Furthermore the index could have been created in the first place via the Search REST API see xref:fts-creating-index-with-rest-api.adoc[Index Creation with REST API] for more information on using the Search REST API syntax. - -[#creating_geospatial_rest_query_radius_based] -[#creating_geopoint_rest_query_radius_based] -== Creating a Query: Radius-Based - -This section and those following, provide examples of the query-bodies required to make geospatial queries with the Couchbase REST API. -Note that more detailed information on performing queries with the Couchbase REST API can be found in xref:fts-searching-with-the-rest-api.adoc[Searching with the REST API]; which shows how to use the full `curl` command and how to incorporate query-bodies into it. - -The following query-body specifies a longitude of `-2.235143` and a latitude of `53.482358`. -The target-field `geo` is specified, as is a `distance` of `100` miles: this is the radius within which target-locations must reside for their documents to be returned. - -[source, json] ----- -{ - "from": 0, - "size": 10, - "query": { - "location": { - "lon": -2.235143, - "lat": 53.482358 - }, - "distance": "100mi", - "field": "geo" - }, - "sort": [ - { - "by": "geo_distance", - "field": "geo", - "unit": "mi", - "location": { - "lon": -2.235143, - "lat": 53.482358 - } - } - ] -} ----- - -The above query contains a `sort` object, which specifies that the returned documents should be ordered in terms of their _geo_distance_ from specified `lon` and `lat` coordinates: these values need not be identical to those specified in the `query` object. - -image::fts-geopoint-search_01.png[,550,align=left] -You can cut-n-paste the above Search body definition into the text area that says "search this index..." - -image::fts-geopoint-search_02.png[,550,align=left] -Once pasted hit the *Search* button and the UI will show the first 10 hits - -image::fts-geopoint-search_03.png[,,align=left] -The console allows searches performed via the UI to be translated dynamically into cURL examples. -To create a cURL command to do this first check *[X] show advanced query settings* and then check *[X] show command-line query example*. - -You should have a cURL command similar to the following: - -[source, console] ----- -curl -XPOST -H "Content-Type: application/json" \ --u : http://localhost:8094/api/index/test_geopoint/query \ --d '{ - "from": 0, - "size": 10, - "query": { - "location": { - "lon": -2.235143, - "lat": 53.482358 - }, - "distance": "100mi", - "field": "geo" - }, - "sort": [ - { - "by": "geo_distance", - "field": "geo", - "unit": "mi", - "location": { - "lon": -2.235143, - "lat": 53.482358 - } - } - ] -}' ----- - -If you copy and then run the above cURL command via the console the response from the Search service will report that there are 847 total_hits but only return the first 10 hits. A subset of formatted console output might appear as follows: - -NOTE: To pretty print the response just pipe the output through the utility *http://stedolan.github.io/jq[jq]* to enhance readability. - -[source, json] ----- -"hits": [ - { - "index": "test_geopoint_7d088ca77bbecbe2_4c1c5584", - "id": "landmark_17411", - "score": 0.025840756648257503, - "sort": [ - " \u0001?E#9>N\f\"e" - ] - }, - { - "index": "test_geopoint_7d088ca77bbecbe2_4c1c5584", - "id": "landmark_17409", - "score": 0.025840756648257503, - "sort": [ - " \u0001?O~i*(kD," - ] - }, - { - "index": "test_geopoint_7d088ca77bbecbe2_4c1c5584", - "id": "landmark_17403", - "score": 0.025840756648257503, - "sort": [ - " \u0001?Sg*|/t\u001f\u0002" - ] - } -] ----- - -[#creating_geospatial_rest_query_bounding_box_based] -[#creating_geoppoint_rest_query_bounding_box_based] -== Creating a Query: Rectangle-Based - -In the following query-body, the `top_left` of a rectangle is expressed by means of an array of two floating-point numbers, specifying a longitude of `-2.235143` and a latitude of `53.482358`. -The `bottom_right` is expressed by means of key-value pairs, specifying a longitude of `28.955043` and a latitude of `40.991862`. -The results are specified to be sorted on `name` alone. - -[source, json] ----- -{ - "from": 0, - "size": 10, - "query": { - "top_left": [-2.235143, 53.482358], - "bottom_right": { - "lon": 28.955043, - "lat": 40.991862 - }, - "field": "geo" - }, - "sort": [ - "name" - ] -} ----- - -A subset of formatted output might appear as follows: - -[source, json] ----- -"hits": [ - { - "index": "test_geopoint_7d088ca77bbecbe2_4c1c5584", - "id": "landmark_16144", - "score": 0.004836809397039384, - "sort": [ - "02" - ] - }, - { - "index": "test_geopoint_7d088ca77bbecbe2_4c1c5584", - "id": "hotel_9905", - "score": 0.01625607942050202, - "sort": [ - "1" - ] - }, - { - "index": "test_geopoint_7d088ca77bbecbe2_4c1c5584", - "id": "hotel_16460", - "score": 0.004836809397039384, - "sort": [ - "11" - ] - }, - { - "index": "test_geopoint_7d088ca77bbecbe2_4c1c5584", - "id": "hotel_21674", - "score": 0.010011952055063241, - "sort": [ - "17" - ] - } -] ----- - -[#creating_geospatial_rest_query_polygon_based] -[#creating_geopoint_rest_query_polygon_based] - -== Creating a Query: Polygon-Based - -The following query-body uses an array, each of whose elements is a string, containing two floating-point numbers; to specify the latitude and longitude of each of the corners of a polygon — known as _polygon points_. -In each string, the `lat` floating-point value precedes the `lon.` - -Here, the last-specified string in the array is identical to the initial string, thus explicitly closing the box. -However, specifying an explicit closure in this way is optional: closure will be inferred by Couchbase Server if not explicitly specified. - -If a target data-location falls within the box, its document is returned. -The results are specified to be sorted on `name` alone. - -[source, json] ----- -{ - "query": { - "field": "geo", - "polygon_points": [ - "37.79393211306212,-122.44234633404847", - "37.77995881733997,-122.43977141339417", - "37.788031092020155,-122.42925715405579", - "37.79026946582319,-122.41149020154114", - "37.79571192027403,-122.40735054016113", - "37.79393211306212,-122.44234633404847" - ] - }, - "sort": [ - "name" - ] -} ----- - -A subset of formatted output might appear as follows: - -[source,json] ----- -"hits": [ - { - "index": "test_geopoint_7d088ca77bbecbe2_4c1c5584", - "id": "landmark_25944", - "score": 0.23634379439298683, - "sort": [ - "4" - ] - }, - { - "index": "test_geopoint_7d088ca77bbecbe2_4c1c5584", - "id": "landmark_25681", - "score": 0.31367419004657393, - "sort": [ - "alta" - ] - }, - { - "index": "test_geopoint_7d088ca77bbecbe2_4c1c5584", - "id": "landmark_25686", - "score": 0.31367419004657393, - "sort": [ - "atherton" - ] - } -] ----- - -NOTE: When we sort on a string that uses the default analyzer that string is tokenized and you may get unexpected results as you are sorting on the tokenized field. If you want to sort on the actual text in the field should use the *analyzer: "keyword"* to sort by the original text in the field. In addition if you want to include the keyword in the index itself you will need to check *[X] store* or check *[X] docvalues*. - -== Sorting by Keywords - -To sort by the actual names we need to take into account that for type="airport" has a field called "airportname" and for type="landmark" has a field called "name". - -By inserting editing the index and inserting two more child fields as follows: - -* for type="airport" -+ -image::fts-geopoint-update1.png[,600,align=left] - -* for type="landmark" -+ -image::fts-geopoint-update2.png[,600,align=left] - -* Click the *Update Index* button - -If you look carefully above both the actual fields "airportname" and "name" will be searchable as name. - -At this point if you Edit the index again the complete definition should look like: - -image::fts-geopoint-updated-index.png[,600,align=left] - -Now repeating the above "Polygon-Based" Query we see that the data is sorted based on the original field names. - -[source,json] ----- -"hits": [ - { - "index": "test_geopoint_6e91b22c20945813_4c1c5584", - "id": "landmark_25681", - "score": 0.31367419004657393, - "sort": [ - "Alta Plaza Park" - ] - }, - { - "index": "test_geopoint_6e91b22c20945813_4c1c5584", - "id": "landmark_25686", - "score": 0.31367419004657393, - "sort": [ - "Atherton House" - ] - }, - { - "index": "test_geopoint_6e91b22c20945813_4c1c5584", - "id": "landmark_25944", - "score": 0.23634379439298683, - "sort": [ - "Big 4 Restaurant" - ] - }, - { - "index": "test_geopoint_6e91b22c20945813_4c1c5584", - "id": "landmark_25739", - "score": 0.31367419004657393, - "sort": [ - "Blu" - ] - }, - { - "index": "test_geopoint_6e91b22c20945813_4c1c5584", - "id": "landmark_36047", - "score": 0.25593551041769463, - "sort": [ - "Cable Car Museum" - ] - }, ----- - -Finally since we checked *[X] store* for the child mappings for both "airportname" and "name" we modify the above “Polygon-Based” by adding *"fields": ["name"],* and then run it in the UI. - -[source, json] ----- -{ - "fields": ["name"], - "query": { - "field": "geo", - "polygon_points": [ - "37.79393211306212,-122.44234633404847", - "37.77995881733997,-122.43977141339417", - "37.788031092020155,-122.42925715405579", - "37.79026946582319,-122.41149020154114", - "37.79571192027403,-122.40735054016113", - "37.79393211306212,-122.44234633404847" - ] - }, - "sort": [ - "name" - ] -} ----- - -Copy and paste the above into the UI's index search text box the result will be as follows: - -image::fts-geopoint-updated-index-seach-stored.png[,,align=left] - -Because we added *"fields": ["name"],* and the fields "airportname" and "name" were specified to be stored the index returns the actual value (the mapped name of name) both in the UI. If we passed the new query body to cURL the value will also be returned via the REST call. diff --git a/modules/fts/pages/fts-supported-queries-geospatial.adoc b/modules/fts/pages/fts-supported-queries-geospatial.adoc deleted file mode 100644 index ae2c9c8e4e..0000000000 --- a/modules/fts/pages/fts-supported-queries-geospatial.adoc +++ /dev/null @@ -1,16 +0,0 @@ -= Geospatial Queries - -[abstract] -_Geospatial_ queries return documents that contain location in either legacy Geopoint format or standard GeoJSON structures. - -== Geopoint (type geopoint) - -Legacy or Geopoint documents which specify a geographical location. - -For these queries the Search service lets users index the single dimensional geopoint/location fields and perform various bounding queries like point-distance, bounded-rectangle and bounded-polygon against the indexed geopoint field. - -For higher level shapes and structures refer to GeoJSON below. - -== GeoJSON (type geojson) - -include::partial$fts-geojson-intro-common.adoc[] diff --git a/modules/fts/pages/fts-supported-queries-match-all.adoc b/modules/fts/pages/fts-supported-queries-match-all.adoc deleted file mode 100644 index 275ff29c39..0000000000 --- a/modules/fts/pages/fts-supported-queries-match-all.adoc +++ /dev/null @@ -1,9 +0,0 @@ -= Match All Query - -Matches _all_ documents in an index, irrespective of terms. -For example, if an index is created on the `travel-sample` bucket for documents of type `zucchini`, the _match all_ query returns all document IDs from the `travel-sample` bucket, even though the bucket contains no documents of type `zucchini`. - -[source,json] ----- -{ "match_all": {} } ----- \ No newline at end of file diff --git a/modules/fts/pages/fts-supported-queries-match-none.adoc b/modules/fts/pages/fts-supported-queries-match-none.adoc deleted file mode 100644 index 1ef2ef25a8..0000000000 --- a/modules/fts/pages/fts-supported-queries-match-none.adoc +++ /dev/null @@ -1,8 +0,0 @@ -= Match None Query - -Matches no documents in the index. - -[source,json] ----- -{ "match_none": {} } ----- diff --git a/modules/fts/pages/fts-supported-queries-match-phrase.adoc b/modules/fts/pages/fts-supported-queries-match-phrase.adoc deleted file mode 100644 index 8ece9a16cc..0000000000 --- a/modules/fts/pages/fts-supported-queries-match-phrase.adoc +++ /dev/null @@ -1,23 +0,0 @@ -= Match Phrase Query - -The input text is analyzed, and a phrase query is built with the terms resulting from the analysis. -This type of query searches for terms in the target that occur _in the positions and offsets indicated by the input_: this depends on _term vectors_, which must have been included in the creation of the index used for the search. - -For example, a match phrase query for `location for functions` is matched with `locate the function`, if the standard analyzer is used: this analyzer uses a _stemmer_, which tokenizes `location` and `locate` to `locat`, and reduces `functions` and `function` to `function`. -Additionally, the analyzer employs _stop_ removal, which removes small and less significant words from input and target text, so that matches are attempted on only the more significant elements of vocabulary: in this case `for` and `the` are removed. -Following this processing, the tokens `locat` and `function` are recognized as _common to both input and target_; and also as being both _in the same sequence as_, and _at the same distance from_ one another; and therefore a match is made. - -== Example - -The following JSON object demonstrates specification of a match phrase query: - - -[source,json] ----- -{ - "match_phrase": "very nice", - "field": "reviews.content" -} ----- - -A demonstration of the match phrase query using the Java SDK can be found in xref:3.2@java-sdk::full-text-searching-with-sdk.adoc[Searching from the SDK]. \ No newline at end of file diff --git a/modules/fts/pages/fts-supported-queries-match.adoc b/modules/fts/pages/fts-supported-queries-match.adoc deleted file mode 100644 index 1df43464e3..0000000000 --- a/modules/fts/pages/fts-supported-queries-match.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[#Match-Query] -= Match Query - -A term without any other syntax is interpreted as a match query for the term in the default field. The default field is `_all`. - -For example, `pool` performs match query for the term `pool`. - -A match query _analyzes_ input text and uses the results to query an index. Options include specifying an analyzer, performing a _fuzzy match_, and performing a _prefix match_. - -By default, the analyzer used for the search text is what was set for the specified field during index creation. For information on analyzers, see xref:fts-analyzers.adoc[Understanding Analyzers]. - -NOTE: If the field is not specified, the match query will target the `_all` field within the index. Including content within the `_all` field is a setting during index creation. - -When fuzzy matching is used, if the single parameter is set to a non-zero integer, the analyzed text is matched with a corresponding level of fuzziness. The maximum supported fuzziness is 2. - -When a prefix match is used, the [.param]`prefix_length` parameter specifies that for a match to occur, a prefix of specified length must be shared by the input-term and the target text-element. - -When an operator field is used, the [.param]`operator` decides the boolean logic used to interpret the text in the match field. - -For example, an operator value of `"and"` means the match query text would be treated like `location` AND `hostel`. -The default operator value of `"or"` means the match query text would be treated like `location` OR `hostel`. - -A demonstration of the match query using the Java SDK can be found in xref:3.2@java-sdk::full-text-searching-with-sdk.adoc[Searching from the SDK]. - -== Example - -The following JSON object demonstrates the specification of a match query: - -[source,json] ----- -{ - "match": "location hostel", - "field": "reviews.content", - "analyzer": "standard", - "fuzziness": 2, - "prefix_length": 4, - "operator": "and" -} ----- - diff --git a/modules/fts/pages/fts-supported-queries-non-analytic-query.adoc b/modules/fts/pages/fts-supported-queries-non-analytic-query.adoc deleted file mode 100644 index ea1c1d1731..0000000000 --- a/modules/fts/pages/fts-supported-queries-non-analytic-query.adoc +++ /dev/null @@ -1,15 +0,0 @@ -= Non-Analytic Queries - -Non-analytic queries do not support analysis on their inputs. -This means that only exact matches are returned. - -The following queries are non-Analytic queries: - -* xref:fts-supported-queries-term.adoc[Term] -* xref:fts-supported-queries-phrase.adoc[Phrase] -* xref:fts-supported-queries-prefix-query.adoc[Prefix] -* xref:fts-supported-queries-regexp.adoc[Regexp] -* xref:fts-supported-queries-fuzzy.adoc[Fuzzy] -* xref:fts-supported-queries-wildcard.adoc[Wildcard] - -For information on analyzers, see xref:fts-index-analyzers.adoc[Understanding Analyzers]. diff --git a/modules/fts/pages/fts-supported-queries-numeric-range.adoc b/modules/fts/pages/fts-supported-queries-numeric-range.adoc deleted file mode 100644 index 833bf9201c..0000000000 --- a/modules/fts/pages/fts-supported-queries-numeric-range.adoc +++ /dev/null @@ -1,38 +0,0 @@ -[#Numeric-Ranges] -= Numeric Range Query - -A _numeric range_ query finds documents containing a numeric value in the specified field within the specified range. - -Define the endpoints using the fields [.param]`min` and [.param]`max`. -You can omit any one endpoint, but not both. - -The [.param]`inclusive_min` and [.param]`inclusive_max` properties control whether or not the endpoints are included or excluded. - -By default, [.param]`min` is inclusive and [.param]`max` is exclusive. - -A demonstration of the numeric range Query using the Java SDK can be found in xref:3.2@java-sdk::full-text-searching-with-sdk.adoc[Searching from the SDK]. - -== Example - -[source,json] ----- -{ - "min": 100, "max": 1000, - "inclusive_min": false, - "inclusive_max": false, - "field": "id" -} ----- - -== Numeric Ranges - -You can specify numeric ranges with the `>`, `>=`, `<`, and `\<=` operators, each followed by a numeric value. - -=== Example - -[source,json] ----- -`reviews.ratings.Cleanliness:>4` ----- - -The above qeury performs numeric range query on the `reviews.ratings.Cleanliness` field, for values greater than 4. \ No newline at end of file diff --git a/modules/fts/pages/fts-supported-queries-phrase.adoc b/modules/fts/pages/fts-supported-queries-phrase.adoc deleted file mode 100644 index 53ce0135ef..0000000000 --- a/modules/fts/pages/fts-supported-queries-phrase.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= Phrase Query - -A _phrase query_ searches for terms occurring at the specified position and offsets. It performs an exact term-match for all the phrase-constituents without using an analyzer. - -[source,json] ----- -{ - "terms": ["nice", "view"], - "field": "reviews.content" -} ----- - -A demonstration of the phrase query using the Java SDK can be found in xref:3.2@java-sdk::full-text-searching-with-sdk.adoc[Searching from the SDK]. - -// #How to specify the position and offset# - -// #Can we specify the full query instead of small chunk?# \ No newline at end of file diff --git a/modules/fts/pages/fts-supported-queries-prefix-query.adoc b/modules/fts/pages/fts-supported-queries-prefix-query.adoc deleted file mode 100644 index 990cc8be04..0000000000 --- a/modules/fts/pages/fts-supported-queries-prefix-query.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= Prefix Query - -A _prefix_ query finds documents containing terms that start with the specified prefix. -Please note that the prefix query is a non-analytic query, meaning it won't perform any text analysis on the query text. - -[source,json] ----- -{ - "prefix": "inter", - "field": "reviews.content" -} ----- diff --git a/modules/fts/pages/fts-supported-queries-query-string-query.adoc b/modules/fts/pages/fts-supported-queries-query-string-query.adoc deleted file mode 100644 index 69fc2f1479..0000000000 --- a/modules/fts/pages/fts-supported-queries-query-string-query.adoc +++ /dev/null @@ -1,18 +0,0 @@ -= Query String Query - -A _query string_ can be used, to express a given query by means of a special syntax. - -[source,json] ----- -{ "query": "+nice +view" } ----- - -A demonstration of a query string Query using the Java SDK can be found in xref:3.2@java-sdk::full-text-searching-with-sdk.adoc[Searching from the SDK]. - -NOTE: The Full Text Searches conducted with the Couchbase Web Console themselves use query strings. -(See xref:fts-searching-from-the-UI.adoc[Searching from the UI].) - -Certain queries supported by FTS are not yet supported by the query string syntax. -These include wildcards and regular expressions. - -More detailed information is provided in xref:fts-query-string-syntax.adoc[Query String Syntax] diff --git a/modules/fts/pages/fts-supported-queries-range-query.adoc b/modules/fts/pages/fts-supported-queries-range-query.adoc deleted file mode 100644 index 299430a67d..0000000000 --- a/modules/fts/pages/fts-supported-queries-range-query.adoc +++ /dev/null @@ -1,9 +0,0 @@ -= Range Queries - -Range Queries:: Accept ranges for dates and numbers, and return documents that contain values within those ranges. - -The following queries are range queries: - -* xref:fts-supported-queries-numeric-range.adoc[Numeric Range] -* xref:fts-supported-queries-date-range.adoc[Date Range] -* xref:fts-supported-queries-term-range.adoc[Term Range] diff --git a/modules/fts/pages/fts-supported-queries-regexp.adoc b/modules/fts/pages/fts-supported-queries-regexp.adoc deleted file mode 100644 index ba2088f375..0000000000 --- a/modules/fts/pages/fts-supported-queries-regexp.adoc +++ /dev/null @@ -1,14 +0,0 @@ -= Regexp Query - -A _regexp_ query finds documents containing terms that match the specified regular expression. -Please note that the regex query is a non-analytic query, meaning it won't perform any text analysis on the query text. - -[source,json] ----- -{ - "regexp": "inter.+", - "field": "reviews.content" -} ----- - -A demonstration of a regexp query using the Java SDK can be found in xref:3.2@java-sdk::full-text-searching-with-sdk.adoc[Searching from the SDK]. diff --git a/modules/fts/pages/fts-supported-queries-special-query.adoc b/modules/fts/pages/fts-supported-queries-special-query.adoc deleted file mode 100644 index d751513547..0000000000 --- a/modules/fts/pages/fts-supported-queries-special-query.adoc +++ /dev/null @@ -1,8 +0,0 @@ -= Special Queries - -_Special_ queries are usually employed either in combination with other queries, or to test the system. - -The following queries are special queries: - -* xref:fts-supported-queries-match-all.adoc[Match All] -* xref:fts-supported-queries-match-none.adoc[Match None] \ No newline at end of file diff --git a/modules/fts/pages/fts-supported-queries-term-range.adoc b/modules/fts/pages/fts-supported-queries-term-range.adoc deleted file mode 100644 index 1d36d4cac1..0000000000 --- a/modules/fts/pages/fts-supported-queries-term-range.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= Term Range Query - -A _term range_ query finds documents containing a term in the specified field within the specified range. -Define the endpoints using the fields [.param]`min` and [.param]`max`. -You can omit one endpoint, but not both. -The [.param]`inclusive_min` and [.param]`inclusive_max` properties control whether or not the endpoints are included or excluded. -By default, [.param]`min` is inclusive and [.param]`max` is exclusive. - -[source,json] ----- -{ - "min": "foo", "max": "foof", - "inclusive_min": false, - "inclusive_max": false, - "field": "desc" -} ----- \ No newline at end of file diff --git a/modules/fts/pages/fts-supported-queries-term.adoc b/modules/fts/pages/fts-supported-queries-term.adoc deleted file mode 100644 index bb197bd70a..0000000000 --- a/modules/fts/pages/fts-supported-queries-term.adoc +++ /dev/null @@ -1,15 +0,0 @@ -= Term Query - -A term query is the simplest possible query. It performs an exact match in the index for the provided term. - -== Example - -[source,json] ----- -{ - "term": "locate", - "field": "reviews.content" -} ----- - -A demonstration of term queries using the Java SDK can be found in xref:3.2@java-sdk::full-text-searching-with-sdk.adoc[Searching from the SDK]. diff --git a/modules/fts/pages/fts-supported-queries-wildcard.adoc b/modules/fts/pages/fts-supported-queries-wildcard.adoc deleted file mode 100644 index c85a6c0dad..0000000000 --- a/modules/fts/pages/fts-supported-queries-wildcard.adoc +++ /dev/null @@ -1,16 +0,0 @@ -= Wildcard Query - -A _wildcard_ query uses a wildcard expression, to search within individual terms for matches. -Wildcard expressions can be any single character (`?`) or zero to many characters (`*`). -Wildcard expressions can appear in the middle or end of a term, but not at the beginning. -Please note that the wildcard query is a non-analytic query, meaning it won't perform any text analysis on the query text. - -[source,json] ----- -{ - "wildcard": "inter*", - "field": "reviews.content" -} ----- - -A demonstration of a wildcard query using the Java SDK can be found in xref:3.2@java-sdk::full-text-searching-with-sdk.adoc[Searching from the SDK]. diff --git a/modules/fts/pages/fts-supported-queries.adoc b/modules/fts/pages/fts-supported-queries.adoc deleted file mode 100644 index 5d9e2b324a..0000000000 --- a/modules/fts/pages/fts-supported-queries.adoc +++ /dev/null @@ -1,31 +0,0 @@ -= Supported Queries -:page-aliases: query-types.adoc - -[abstract] -With Full Text Search you can perform queries on Full Text Indexes. You can perform the queries either by using Couchbase Web Console, the Couchbase REST API, {sqlpp} (using search functions in the Query service), or the Couchbase SDK. - -[#query-specification-options] -== Query-Specification Options - -Full Text Search allows a range of query options. These include: - -* Input-text and target-text can be _analyzed_: this transforms input-text into _token-streams_, according to different specified criteria, so allowing richer and more finely controlled forms of text-matching. -* The _fuzziness_ of a query can be specified so that the scope of matches can be constrained to a particular level of exactitude. -A high degree of fuzziness means that a large number of partial matches may be returned. -* Multiple queries can be specified for simultaneous processing, with one given a higher _boost_ than another, so ensuring that its results are returned at the top of the set. -* _Regular expressions_ and _wildcards_ can be used in text-specification for search-input. -* _Compound_ queries can be designed, such that appropriate conjunction or disjunction of the total result-set can be returned. - -For information on how to execute queries, see xref:fts-searching-from-the-UI.adoc[Searching from the UI]. - -This section includes the following supported queries: - -* xref:fts-supported-queries-query-string-query.adoc[Query String Query] -* xref:fts-supported-queries-match.adoc[Match] -* xref:fts-supported-queries-match-phrase.adoc[Match Phrase] -* xref:fts-supported-queries-non-analytic-query.adoc[Non Analytic] -* xref:fts-supported-queries-compound-query.adoc[Compound] -* xref:fts-supported-queries-range-query.adoc[Range] -* xref:fts-supported-queries-geo-spatial.adoc[Geospatial] -* xref:fts-supported-queries-special-query.adoc[Special] -* xref:fts-supported-queries-query-options.adoc[Query Options] diff --git a/modules/fts/pages/fts-type-identifiers.adoc b/modules/fts/pages/fts-type-identifiers.adoc deleted file mode 100644 index 3b70e88f09..0000000000 --- a/modules/fts/pages/fts-type-identifiers.adoc +++ /dev/null @@ -1,28 +0,0 @@ -= Specifying Type Identifiers - -A _type identifier_ allows the documents in a bucket to be identified filtered for inclusion into the index according to their _type_. When the *Add Index, Edit Index*, or *Clone Index* screen is accessed, a *Type Identifier* panel is displayed: - -[#type_identifier_image] -image::fts-type-identifier-ui.png[,75%] - -There are three options, each of which gives the index a particular way of determining the type of each document in the bucket. -This document filtering via the *Type Identifier* is only active is you append a `.` and then a `substring` to the end of the `scope.collection` in the Type Mapping. - -== JSON type field -It is the name of a document field. The value specified for this field is used by the index to determine the type of document. - -NOTE: FTS Indexing does not work for fields having a dot (. or period) in the field name. Users must avoid adding a dot (. or period) in the field name. + -*Unsupported field names*: `field.name` or `country.name`. For example, `{ "database.name": "couchbase"}` + -*Supported field names*: `fieldname` or `countryname`. For example, `{ "databasename": "couchbase"}` - -The default value is type: meaning that the index searches for a field in each document whose name is type. - -Each document that contains a field with that name is duly included in the index, with the value of the field specifying the type of the document. - -NOTE: The value of the field should be of text type and cannot be an array or JSON object. - -== Doc ID up to separator -The characters in the ID of each document, up to but not including the separator. For example, if the document’s ID is `hotel_10123`, the value `hotel` is determined by the index to be the type of document. The value entered into the field should be the separator-character used in the ID: for example, `_`, if that character is the underscore - -== Doc ID with regex -A *https://github.com/google/re2/wiki/Syntax[RE2]* regular expression that is applied by the index to the ID of each document. The resulting value is determined to be the type of the document. (This option may be used when the targeted document-subset contains neither a suitable *JSON type field* nor an ID that follows a naming convention suitable for *Doc ID up to separator*.) The value entered into the field should be the regular expression to be used. diff --git a/modules/fts/pages/fts-type-mapping-specifying-fields.adoc b/modules/fts/pages/fts-type-mapping-specifying-fields.adoc deleted file mode 100644 index 82ebb967aa..0000000000 --- a/modules/fts/pages/fts-type-mapping-specifying-fields.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[#specifying-fields-for-type-mapping] -= Specifying fields for Type Mapping - -A Full Text Index can be defined not only to include (or exclude) documents of a certain type but also to include (or exclude) specified fields within each of the typed documents. - -To specify one or more fields, hover with the mouse cursor over a row in the Type Mappings panel that contains an enabled type mapping. Buttons labeled *edit* and *+* appear: - -image::fts-type-mappings-ui-fields-buttons.png[,700,align=left] - -Left-clicking on the *edit* button displays the following interface: - -image::fts-type-mappings-ui-edit.png[,500,align=left] - -This allows the mapping to be deleted or associated with a different analyzer. - -NOTE: FTS Indexing does not work for fields having a dot (. or period) in the field name. Users must avoid adding dot (. or period) in the field name. Like using `field.name` or `country.name` is not supported. For example, `{ "database.name": "couchbase"}` - -If the *only index specified fields* checkbox is checked, only fields specified by the user are included in the index. - -Left-clicking on the *+* button displays a pop-up that features two options: - -image::fts-type-mappings-ui-field-options.png[,700,align=left] - -These options are described in the following sections. - -* xref:fts-type-mappings-add-child-mappings.adoc[Add Child Mapping] -* xref:fts-type-mappings-add-child-field.adoc[Add Child Field] \ No newline at end of file diff --git a/modules/fts/pages/fts-type-mappings-Docid-with-regexp.adoc b/modules/fts/pages/fts-type-mappings-Docid-with-regexp.adoc deleted file mode 100644 index 67b19f2031..0000000000 --- a/modules/fts/pages/fts-type-mappings-Docid-with-regexp.adoc +++ /dev/null @@ -1,66 +0,0 @@ -= DocID with regexp in Type Mappings - -“Doc ID with regexp” is another way the search service allows the user to extract “type identifiers” for indexing. - -* Set up a valid regular expression within docid_regexp. Remember this will be applied on the document IDs. -* Choose a type mapping name that is considered a match for the regexp. -* The type mapping name CANNOT be a regexp. - -For example, while working with the `travel-sample` bucket, set up docid_regexp to `air[a-z]{4}` and use the following type mappings. -* airline -* airport - -Below is a full index definition using it. -{ - "name": "airline-airport-index", - "type": "fulltext-index", - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "air[a-z]{4}", - "mode": "docid_regexp", - "type_field": "type" - }, - "mapping": { - "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": { - "airline": { - "dynamic": true, - "enabled": true - }, - "airport": { - "dynamic": true, - "enabled": true - } - } - }, - "store": { - "indexType": "scorch", - "segmentVersion": 15 - } - }, - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "sourceParams": {}, - "planParams": { - "indexPartitions": 1 - } -} - -So setting this as the index definition would index all attributes of documents with “airline” or "airport" in its document IDs. - -image::fts-type-mapping-regexp-with-docid.png[,750,align=left] - -Note: The golang regexp support is based on -xref:https://github.com/google/re2/wiki/Syntax[Access the github link] diff --git a/modules/fts/pages/fts-type-mappings-add-child-field-analyzer.adoc b/modules/fts/pages/fts-type-mappings-add-child-field-analyzer.adoc deleted file mode 100644 index a2eaba9ba3..0000000000 --- a/modules/fts/pages/fts-type-mappings-add-child-field-analyzer.adoc +++ /dev/null @@ -1,9 +0,0 @@ -= Child Field Analyzer - -An analyzer optionally to be used for the field. -The list of available analyzers can be displayed by means of the field's pull-down menu, and can be selected from. - -== Example - -image::fts-type-mappings-child-field-analysers.png[,200,align=left] - diff --git a/modules/fts/pages/fts-type-mappings-add-child-field-docvalues.adoc b/modules/fts/pages/fts-type-mappings-add-child-field-docvalues.adoc deleted file mode 100644 index babf2aca70..0000000000 --- a/modules/fts/pages/fts-type-mappings-add-child-field-docvalues.adoc +++ /dev/null @@ -1,13 +0,0 @@ -= Child Field DocValues - -To include the value for each instance of the field in the index, the docvalues checkbox must be checked. This is essential for xref:fts-search-response-facets.adoc[Facets]. - -For sorting of search results based on field values: see xref:fts-sorting.adoc[Sorting Query Results]. - -By default, this checkbox is selected. If it is _unchecked_, the values are _not_ added to the index; and in consequence, neither Search Facets nor value-based result-sorting is supported. - -== Example - -image::fts-type-mappings-child-field-docvalues.png[,750,align=left] - -NOTE: When this checkbox is checked, the resulting index will increase proportionately in size. \ No newline at end of file diff --git a/modules/fts/pages/fts-type-mappings-add-child-field-field-name.adoc b/modules/fts/pages/fts-type-mappings-add-child-field-field-name.adoc deleted file mode 100644 index bd3f7f2e29..0000000000 --- a/modules/fts/pages/fts-type-mappings-add-child-field-field-name.adoc +++ /dev/null @@ -1,8 +0,0 @@ -= Child Field Name - -The name of any field within the document that contains a single value or an array, rather than a JSON object. - - -== Example - -image::fts-type-mappings-child-field-field-name.png[,750,align=left] \ No newline at end of file diff --git a/modules/fts/pages/fts-type-mappings-add-child-field-field-searchable-as.adoc b/modules/fts/pages/fts-type-mappings-add-child-field-field-searchable-as.adoc deleted file mode 100644 index 795301304c..0000000000 --- a/modules/fts/pages/fts-type-mappings-add-child-field-field-searchable-as.adoc +++ /dev/null @@ -1,8 +0,0 @@ -= Child Field Searchable As - -Typically identical to the [.ui]*field* (and dynamically supplied during text-input of the [.ui]*field*-value). -This can be modified, to indicate an alternative field-name, whose associated value thereby becomes included in the indexed content, rather than that associated with the field-name specified in *field*. - -== Example - -image::fts-type-mappings-child-field-field-searchable-as.png[,750,align=left] \ No newline at end of file diff --git a/modules/fts/pages/fts-type-mappings-add-child-field-field-type.adoc b/modules/fts/pages/fts-type-mappings-add-child-field-field-type.adoc deleted file mode 100644 index 01ad86e447..0000000000 --- a/modules/fts/pages/fts-type-mappings-add-child-field-field-type.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= Child Field Type - -The _data-type_ of the value of the field. -This can be `text`, `number`, `datetime`, `boolean`, `disabled`, or `geopoint`; and can be selected from the field's pull-down menu, as follows: - -[#fts_type_mappings_ui_select_data_type] -image::fts-type-mappings-ui-select-data-type.png[,300,align=left] - -== Example - -image::fts-type-mappings-child-field-type.png[,750,align=left] \ No newline at end of file diff --git a/modules/fts/pages/fts-type-mappings-add-child-field-include-in-all-field.adoc b/modules/fts/pages/fts-type-mappings-add-child-field-include-in-all-field.adoc deleted file mode 100644 index 1de8838469..0000000000 --- a/modules/fts/pages/fts-type-mappings-add-child-field-include-in-all-field.adoc +++ /dev/null @@ -1,16 +0,0 @@ -= Child Field - Include in_all field: - -When checked, the field is included in the definition of [.ui]*_all*, which is the field specified by default in the [.ui]*Advanced* panel. -When unchecked, the field is not included. - -Inclusion means when _query strings_ are used to specify searches, the text in the current field is searchable without the field name requiring a prefix. -For Example, a search on description:modern can be accomplished simply by specifying the word ‘modern’. This is applicable for all query types and not just limited to query string query type. - - -== Example - -image::fts-type-mappings-child-field-include-in-all.png[,750,align=left] - -NOTE: "include in _all" will write a copy of the tokens generated for a particular field to the "_all" composite field. When this checkbox is checked, the resulting index will proportionately increase in size. - -Enabling this option results in larger indexes, so disable this option to always use field scoped queries in the search requests. diff --git a/modules/fts/pages/fts-type-mappings-add-child-field-include-term-vectors.adoc b/modules/fts/pages/fts-type-mappings-add-child-field-include-term-vectors.adoc deleted file mode 100644 index 1f4283d11a..0000000000 --- a/modules/fts/pages/fts-type-mappings-add-child-field-include-term-vectors.adoc +++ /dev/null @@ -1,14 +0,0 @@ -= Child Field - Include term vectors - -When checked, term vectors are included. -When unchecked, term vectors are not included. - -Term vectors are the locations of terms in a particular field. -Certain kinds of functionality (such as highlighting, and phrase search) require term vectors. -Inclusion of term vectors results in larger indexes and correspondingly slower index build-times. - -== Example - -image::fts-type-mappings-child-field-termvectors.png[,750,align=left] - -NOTE: "include term vectors" indexes the array positions (locations) of the terms within the field (needed for phrase searching and highlighting). When this checkbox is checked, the resulting index will proportionately increase in size. diff --git a/modules/fts/pages/fts-type-mappings-add-child-field-index.adoc b/modules/fts/pages/fts-type-mappings-add-child-field-index.adoc deleted file mode 100644 index 8595dcb93c..0000000000 --- a/modules/fts/pages/fts-type-mappings-add-child-field-index.adoc +++ /dev/null @@ -1,10 +0,0 @@ -= Child Field Index - -When checked, the field is indexed; when unchecked, the field is not indexed. -This may be used, therefore, to explicitly remove an already-defined field from the index. - -== Example - -image::fts-type-mappings-child-field-index.png[,750,align=left] - -NOTE: When this checkbox is checked, the resulting index will proportionately increase in size. \ No newline at end of file diff --git a/modules/fts/pages/fts-type-mappings-add-child-field-store.adoc b/modules/fts/pages/fts-type-mappings-add-child-field-store.adoc deleted file mode 100644 index c171f9feeb..0000000000 --- a/modules/fts/pages/fts-type-mappings-add-child-field-store.adoc +++ /dev/null @@ -1,22 +0,0 @@ -= Child Field Store - -When the child field 'store' option is checked, the original field content is included in the FTS index, enabling the retrieval of stored field values during a search operation. - -When unchecked, the original field content is not included in the FTS index. Storing the field within the index is necessary to support highlighting, which also needs "term vectors” for the field to be indexed. - -== Example -image::fts-type-mappings-child-field-store.png[,700,align=left] - -Ideally, enabling this 'Child Field Store' option has a sizing aspect to the index definition. This option also permits highlighting of search texts in the returned results, so that matched expressions can be easily seen. However, enabling this option also results in larger indexes and slightly longer indexing times. -The field content will show up in queries (when the index has the store option checked) only when requested. There is a ‘fields’ section in the query for it. - ----- -{ -"query": {...}, -"fields": ["store_field_name"] -} -Setting "fields" to ["*"] will include the contents of all stored fields in the index. ----- - -NOTE: "store" - writes a copy of the field content into the index. When this checkbox is checked, the resulting index will proportionately increase in size. - diff --git a/modules/fts/pages/fts-type-mappings-add-child-field.adoc b/modules/fts/pages/fts-type-mappings-add-child-field.adoc deleted file mode 100644 index 57730dd77c..0000000000 --- a/modules/fts/pages/fts-type-mappings-add-child-field.adoc +++ /dev/null @@ -1,42 +0,0 @@ -= Add Child Field - -The option [.ui]*insert child field* allows a field to be individually included for (or excluded from) indexing, provided that it contains a single value or an array rather than a JSON object. -Selecting this option displays the following: - -[#fts_type_mappings_child_field_dialog] -image::fts-type-mappings-child-field-dialog.png[,700,align=left] - -The interactive fields and checkboxes are: - -** xref:fts-type-mappings-add-child-field-field-name.adoc[Field Name] - -** xref:fts-type-mappings-add-child-field-field-type.adoc[Field Type] - -** xref:fts-type-mappings-add-child-field-field-searchable-as.adoc[Field Searchable As] - -** xref:fts-type-mappings-add-child-field-analyzer.adoc[Analyzer] - -** xref:fts-type-mappings-add-child-field-index.adoc[Index] - -** xref:fts-type-mappings-add-child-field-store.adoc[Store] - -** xref:fts-type-mappings-add-child-field-include-term-vectors.adoc[Include term vectors] - -** xref:fts-type-mappings-add-child-field-include-in-all-field.adoc[Include in _all field] - -** xref:fts-type-mappings-add-child-field-docvalues.adoc[DocValues] - - - -The dialog, when completed, might look as follows: - -[#fts_type-mappings_child_field_dialog_complete] -image::fts-type-mappings-child-field-dialog-complete.png[,700,align=left] - -Left-click on [.ui]*OK*. -The field is saved, and its principal attributes displayed on a new row: - -[#fts_type-mappings_child_field_saved] -image::fts-type-mappings-child-field-saved.png[,700,align=left] - -Note that when this row is hovered over with the mouse, an *Edit* button appears, whereby updates to the definition can be made. diff --git a/modules/fts/pages/fts-type-mappings-add-child-mappings.adoc b/modules/fts/pages/fts-type-mappings-add-child-mappings.adoc deleted file mode 100644 index 260b7a04d1..0000000000 --- a/modules/fts/pages/fts-type-mappings-add-child-mappings.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[#inserting-a-child-mapping] -= Add Child Mapping - -The option [.ui]*insert child mapping* specifies a document-field whose value is a JSON object. -Selecting this option displays the following: - -[#fts_type_mappings_child_mapping_dialog] -image::fts-type-mappings-child-mapping-dialog.png[,700,align=left] - -The following interactive field and checkbox are displayed: - -* [.ui]*{}*: The name of a field whose value is a JSON object. -Note that an analyzer for the field, by means of the pull-down menu. -* [.ui]*only index specified fields*: When checked, only fields explicitly specified are added to the index. -Note that the JSON object specified as the value for [.ui]*{}* has multiple fields of its own. -Checking this box ensures that all or a subset of these can be selected for indexing. - -When completed, this panel might look as follows (note that `reviews` is a field within the `hotel`-type documents of the `travel-sample` bucket whose value is a JSON object): - -[#fts_type_mappings_child_mapping_dialog_complete] -image::fts-type-mappings-child-mapping-dialog-complete.png[,700,align=left] - -Save by left-clicking *OK*. -The field is now displayed as part of the `hotel` type mapping. -Note that by hovering over the `reviews` row with the mouse, the [.ui]*Edit* and [.ui]*+* buttons are revealed: the [.ui]*+* button is present because `reviews` is an object that contains child-fields; which can now themselves be individually indexed. -Left-click on this, and a child-field, such as `content`, can be specified: - -[#fts_type_mappings_child_mapping_add_field] -image::fts-type-mappings-child-mapping-add-field.png[,700,align=left] \ No newline at end of file diff --git a/modules/fts/pages/fts-type-mappings.adoc b/modules/fts/pages/fts-type-mappings.adoc deleted file mode 100644 index b2214e170d..0000000000 --- a/modules/fts/pages/fts-type-mappings.adoc +++ /dev/null @@ -1,465 +0,0 @@ -[#specifying-type-mappings] -= Specifying Type Mappings - -[abstract] -Whereas a _type identifier_ tells the index how to determine the position in each document of the characters that specify the document's type, a _type mapping_ specifies the characters themselves. - -If *Doc ID up to separator* is used as a type identifier, and the underscore is specified as the separator-character, a type mapping of _hotel_ ensures that `hotel_10123`, rather than `airline_10`, is indexed. - -When the [.ui]*Add Index*, [.ui]*Edit Index*, or [.ui]*Clone Index* screen is accessed, the [.ui]*Type Mappings* panel can be opened. - -The default setting is displayed: - -[#fts_type_mappings_ui_closed] -image::fts-type-mappings-ui-closed.png[,750,align=left] - -Left-click on the *+ Add Type Mapping* button. -The display now appears as follows: - -[#fts_type_mappings_ui_add] -image::fts-type-mappings-ui-add.png[,750,align=left] - -The display indicates that a single type mapping is currently defined, which is `default`. - -This is a special type mapping created by every index automatically: it is applied to each document whose type _either_ does not match a user-specified type mapping, _or_ has no recognized type attribute. -Therefore, if the default mapping is left enabled, all documents are included in the index, regardless of whether the user actively specifies type mappings. - -To ensure that only documents corresponding to the user's specified type mappings are included in the index, the default type mapping must be disabled (see below for an example). - -Each type mapping is listed as either *dynamic*, meaning that all fields are considered available for indexing, or *only index specified fields*, meaning that only fields specified by the user are indexed. - -Therefore, specifying the default index with dynamic mapping creates a large index whose response times may be relatively slow; and is, as such, an option potentially unsuitable for the most production deployments. - -For information on how values are data-typed when dynamic mapping is specified, see the section below, xref:#document-fields-and-data-types[Document Fields and Data Types]. - -To specify a type mapping, type an appropriate string (for example, `hotel`) into the interactive text field. -Note the [.ui]*only index specified fields* checkbox: if this is checked, only user-specified fields from the document are included in the index. -(For an example, see xref:fts-type-mapping-specifying-fields.adoc[Specifying Fields], below.) - -Optionally, an _analyzer_ can be specified for the type mapping: for all queries that do indeed support the use of an analyzer, the specified analyzer will be applied, rather than the default analyzer (which is itself specified in the *Advanced* pane, as described below, in xref:fts-creating-index-specifying-advanced-settings.adoc[Specifying Advanced Settings]). - -A list of available analyzers can be accessed and selected from, by means of the pull-down menu to the right of the interactive text-field: - -[#fts_type_mappings_ui_analyzers_menu] -image::fts-type-mappings-ui-analyzers-menu.png[,620,align=left] - -The default value, `inherit`, means that the type mapping inherits the default analyzer. -Note that custom analyzers can be created and stored for the index that is being defined using the [.ui]*Analyzers* panel, described below in xref:fts-analyzers.adoc#Creating-Analyzers[Creating Analyzers]. -On creation, all custom analyzers are available for association with a type mapping, and so appear in the pull-down menu shown above. - -Additional information on analyzers can also be found on the page xref:fts-analyzers.adoc#Understanding-Analyzers[Understanding Analyzers]. - -The [.ui]*Type Mappings* panel now appears as follows: - -[#fts_type_mappings_ui_addition_both_checked] -image::fts-type-mappings-ui-addition-both-checked.png[,750,align=left] - -Note that the checkbox to the left of each of the two specified type mappings, `hotel` and `default`, is checked. - -Because `default` is checked, _all_ documents in the bucket (not merely those that correspond to the `hotel` type mapping) will be included in the index. -To ensure that only `hotel` documents are included, _uncheck_ the checkbox for `default`. -The panel now appears as follows: - -[#fts_type_mappings_ui_addition_default_unchecked] -image::fts-type-mappings-ui-addition-default-unchecked.png[,750,align=left] - -Note also that should you wish to ensure that all documents in the bucket are included in the index _except_ those that correspond to the `hotel` type mapping, _uncheck_ the checkbox for `hotel`, and _check_ the `default` checkbox: - -[#fts_type_mappings_ui_addition_default_checked] -image::fts-type-mappings-ui-addition-default-checked.png[,750,align=left] - -== Specifying Type Mapping for Collection - -Type Mapping will allow you to search for documents from the selected scope, selected collections from the scope, and for a specific document type from the selected scope and collections. - -For using non-default scope/collections, please refer: xref:fts-creating-index-from-UI.adoc#using-non-default-scope-collections[Using Non-Default Scope/Collections]. - -** Left click on the *+ Add Type Mapping* button. The display now appears as follows: - -image::fts-type-mapping-for-collection.png[,700,align=left] - -In the Type Mappings, you can add mapping of a *single collection* or *multiple collections*. To specify the collection, click the Collection drop-down list and select the required collection. - -The *Collection* field displays the selected collection along with the selected scope. For example, inventory.airport or inventory.hotel. - -** Click ok to add the collection to the index. Continue the same process to add other collections to the index. - -NOTE: In Type Mappings, you can add multiple collections to the index. However, you can either select only one collection to create a single collection index or select multiple collections to create an index with multiple collections. - -The Type Mappings panel appears as follows: - -== Type Mapping with Single Collection - -With a single collection index, you can search documents only from a single collection specified in the Type Mappings. - -image::fts-type-mappings-single-collection.png[,750,align=left] - -== Type Mapping with Multiple Collections - -With multiple collections index, you can search documents across multiple collections (within a single scope) specified in the Type Mappings. - -image::fts-type-mappings-multiple-collections.png[,750,align=left] - -== Type Mapping with Specific Document Type - -With a specific document type, you can search documents of a specific type from a single collection or multiple collections. Every document in Couchbase includes the type field that represents the type of the document. For example, the type “airport” represents the documents related to airport information. - -image:fts-type-mapping-with-specific-document-type.png[,,align=left] - -If you want to search for a specific document type from a single collection or multiple collections, you can manually specify the document type after the collection in the Collection field. For example, inventory.airline.airport or inventory.route.airport. - -Now, when you search for the airport document type, the index will display all documents from a single collection or multiple collections where the type field is the airport. - -image:fts-display-type-field.png[,750,align=left] - -You can click the document link and verify the document type. - -[#document-type-with-single-collections] -== Document Type with single collection - -Every document in Couchbase includes the type field that represents the type of the document. For example, type “airport” represents the documents related to airport information. - -If you want to search for a specific document type from a single collection, you can manually specify the document type after the collection in the Collection field. - -For example, inventory.airline.airport or inventory.route.airport - -image:fts-type-mapping-specific-document-type-single-collection.png[,750,align=left] - -Now, when you search for the airport document type, the index will display all documents from a single collection where the type field is airport. - -[#document-type-with-multiple-collections] -== Document Type with multiple collections - -Every document in Couchbase includes the type field that represents the type of the document. For example, type “airport” represents the documents related to airport information. - -If you want to search for a specific document type from the multiple collections, you can manually specify the document type after the collection in the Collection field. - -For example, inventory.airline.airport or inventory.route.airport - -image:fts-type-mapping-specific-document-type-multiple-collections.png[,750,align=left] - -Now, when you search for the airport document type, the index will display all documents from the multiple collections where the type field is airport. - -[#document-fields-and-data-types] -== Document-Fields and Data-Types - -During index creation, for each document-field for which the data-type has not been explicitly specified (which is to say, *text*, *number*, *datetime*, *boolean*, *disabled*, *geopoint*, or *geoshape*), the field-value is examined, and the best-possible determination made, as follows: - -|=== -| Type of JSON value | Indexed as\... - -| Boolean -| Boolean - -| Number -| Number - -| String containing a date -| Date - -| String (not containing a date) -| String - -| Geopoint -| A xref:fts-supported-queries-geopoint-spatial.adoc#recognizing_target_data[legacy lat/lon pair] - -| Geoshape -| A xref:fts-supported-queries-geojson-spatial.adoc#supported-geojson-data-types[GeoJSON shape] - -|=== - -NOTE: The indexer attempts to parse String date-values as dates, and indexes them as such if the operation succeeds. However, on query-execution, Full Text Search expects dates to be in the format specified by https://www.ietf.org/rfc/rfc3339.txt[RFC-3339^], which is a specific profile of ISO-8601. - -The String values such as `7` or `true` remains as Strings and did not index as numbers or Booleans respectively. - -The number-type is modeled as a 64-bit floating-point value internally. - -[#exclude-fields-from-dynamic-fts-index] -== Excluding child field/ child mapping from a dynamic FTS index - -If you want to index everything except a child field or a child mapping, you add that child mapping and child field and turn off the child mapping and the *Index* option, respectively. - -Perform the following steps: - -1. In the index, add a type mapping and set it to dynamic. -2. In the type mapping, add a child field. -3. For the fields, uncheck the *Index* option from its settings. -4. For the mapping, uncheck the corresponding dynamic type mapping check box to disable it. - -[#specifying-fields-for-type-mapping] -== Specifying fields for Type Mapping - -A Full Text Index can be defined not only to include (or exclude) documents of a certain type but also to include (or exclude) specified fields within each of the typed documents. - -To specify one or more fields, hover with the mouse cursor over a row in the Type Mappings panel that contains an enabled type mapping. Buttons labeled *edit* and *+* appear: - -image::fts-type-mappings-ui-fields-buttons.png[,700,align=left] - -Left-clicking on the *edit* button displays the following interface: - -image::fts-type-mappings-ui-edit.png[,700,align=left] - -This allows the mapping to be deleted or associated with a different analyzer. - -NOTE: FTS Indexing does not work for fields having a dot (. or period) in the field name. Users must avoid adding dot (. or period) in the field name. Like using `field.name` or `country.name` is not supported. For example, `{ "database.name": "couchbase"}` - -If the *only index specified fields* checkbox is checked, only fields specified by the user are included in the index. - -Left-clicking on the *+* button displays a pop-up that features two options: - -image::fts-type-mappings-ui-field-options.png[,700,align=left] - -These options are described in the following sections. - -* xref:fts-type-mappings-add-child-mappings.adoc[Add Child Mapping] -* xref:fts-type-mappings-add-child-field.adoc[Add Child Field] - -[#inserting-a-child-mapping] -== Add Child Mapping - -The option [.ui]*insert child mapping* specifies a document-field whose value is a JSON object. -Selecting this option displays the following: - -[#fts_type_mappings_child_mapping_dialog] -image::fts-type-mappings-child-mapping-dialog.png[,700,align=left] - -The following interactive field and checkbox are displayed: - -* [.ui]*{}*: The name of a field whose value is a JSON object. -Note that an analyzer for the field is specified by means of the pull-down menu. -* [.ui]*only index specified fields*: When checked, only fields explicitly specified are added to the index. -Note that the JSON object specified as the value for [.ui]*{}* has multiple fields of its own. -Checking this box ensures that all or a subset of these can be selected for indexing. - -When completed, this panel might look as follows (note that `reviews` is a field within the `hotel`-type documents of the `travel-sample` bucket whose value is a JSON object): - -[#fts_type_mappings_child_mapping_dialog_complete] -image::fts-type-mappings-child-mapping-dialog-complete.png[,700,align=left] - -Save by left-clicking *OK*. -The field is now displayed as part of the `hotel` type mapping. -Note that by hovering over the `reviews` row with the mouse, the [.ui]*Edit* and [.ui]*{plus}* buttons are revealed: the [.ui]*+* button is present because `reviews` is an object that contains child-fields; which can now themselves be individually indexed. -Left-click on this, and a child-field, such as `content`, can be specified: - -[#fts_type_mappings_child_mapping_add_field] -image::fts-type-mappings-child-mapping-add-field.png[,700,align=left] - - -== Add Child Field - -The option [.ui]*insert child field* allows a field to be individually included for (or excluded from) indexing, provided that it contains a single value or an array rather than a JSON object. -Selecting this option displays the following: - -[#fts_type_mappings_child_field_dialog] -image::fts-type-mappings-child-field-dialog.png[,700,align=left] - -The interactive fields and checkboxes are: - -* *Field Name* -* *Field Type* -* *Field Searchable As* -* *Analyzer* -* *Index* -* *Store* -* *Include term vectors* -* *Include in _all field* -* *DocValues* - -=== Field Name - -The name of any field within the document that contains a single value or an array, rather than a JSON object. - -==== Example - -image::fts-type-mappings-child-field-field-name.png[,750,align=left] - -=== Field Type - -The _data-type_ of the value of the field. -This can be `text`, `number`, `datetime`, `boolean`, `disabled`, or `geopoint`; and can be selected from the field's pull-down menu, as follows: - -[#fts_type_mappings_ui_select_data_type] -image::fts-type-mappings-ui-select-data-type.png[,750,align=left] - -==== Example - -image::fts-type-mappings-child-field-type.png[,750,align=left] - -=== Field Searchable As - -Typically identical to the [.ui]*field* (and dynamically supplied during text-input of the [.ui]*field*-value). -This can be modified, to indicate an alternative field-name, whose associated value thereby becomes included in the indexed content, rather than that associated with the field-name specified in *field*. - -==== Example - -image::fts-type-mappings-child-field-field-searchable-as.png[,750,align=left] - -=== Field Analyzer - -An analyzer optionally to be used for the field. -The list of available analyzers can be displayed by means of the field's pull-down menu, and can be selected from. - -==== Example - -image::fts-type-mappings-child-field-analysers.png[,750,align=left] - -=== Index - -When checked, the field is indexed; when unchecked, the field is not indexed. -This may be used, therefore, to explicitly remove an already-defined field from the index. - -==== Example - -image::fts-type-mappings-child-field-index.png[,750,align=left] - -NOTE: When this checkbox is checked, the resulting index will proportionately increase in size. - -=== Store - -When the child field `store` option is checked, the original field content is included in the FTS index, enabling the retrieval of stored field values during a search operation. - -When unchecked, the original field content is not included in the FTS index. Storing the field within the index is necessary to support highlighting, which also needs "term vectors” for the field to be indexed. - -==== Example -image::fts-type-mappings-child-field-store.png[,700,align=left] - -Ideally, enabling this `Child Field Store` option has a sizing aspect to the index definition. This option also permits highlighting of search texts in the returned results, so that matched expressions can be easily seen. However, enabling this option also results in larger indexes and slightly longer indexing times. -The field content will show up in queries (when the index has the store option checked) only when requested. There is a ‘fields’ section in the query for it. - ----- -{ -"query": {...}, -"fields": ["store_field_name"] -} -Setting "fields" to ["*"] will include the contents of all stored fields in the index. ----- - -NOTE: "store" - writes a copy of the field content into the index. When this checkbox is checked, the resulting index will proportionately increase in size. - -=== Include term vectors - -When checked, term vectors are included. -When unchecked, term vectors are not included. - -Term vectors are the locations of terms in a particular field. -Certain kinds of functionality (such as highlighting, and phrase search) require term vectors. -Inclusion of term vectors results in larger indexes and correspondingly slower index build-times. - -==== Example - -image::fts-type-mappings-child-field-termvectors.png[,750,align=left] - -NOTE: "include term vectors" indexes the array positions (locations) of the terms within the field (needed for phrase searching and highlighting). When this checkbox is checked, the resulting index will proportionately increase in size. - -=== Include in_all field: - -When checked, the field is included in the definition of [.ui]*+_all+*, which is the field specified by default in the [.ui]*Advanced* panel. -When unchecked, the field is not included. - -Inclusion means when _query strings_ are used to specify searches, the text in the current field is searchable without the field name requiring a prefix. -For Example, a search on description:modern can be accomplished simply by specifying the word ‘modern’. This is applicable for all query types and not just limited to query string query type. - -==== Example - -image::fts-type-mappings-child-field-include-in-all.png[,750,align=left] - -NOTE: "include in _all" will write a copy of the tokens generated for a particular field to the "_all" composite field. When this checkbox is checked, the resulting index will proportionately increase in size. - -Enabling this option results in larger indexes, so disable this option to always use field scoped queries in the search requests. - -=== DocValues - -To include the value for each instance of the field in the index, the docvalues checkbox must be checked. This is essential for xref:fts-search-response-facets.adoc[Facets]. - -For sorting of search results based on field values: see xref:fts-sorting.adoc[Sorting Query Results]. - -By default, this checkbox is selected. If it is _unchecked_, the values are _not_ added to the index; and in consequence, neither Search Facets nor value-based result-sorting is supported. - -==== Example - -image::fts-type-mappings-child-field-docvalues.png[,750,align=left] - -NOTE: When this checkbox is checked, the resulting index will increase proportionately in size. - -The dialog, when completed, might look as follows: - -[#fts_type-mappings_child_field_dialog_complete] -image::fts-type-mappings-child-field-dialog-complete.png[,700,align=left] - -Left-click on [.ui]*OK*. -The field is saved, and its principal attributes displayed on a new row: - -[#fts_type-mappings_child_field_saved] -image::fts-type-mappings-child-field-saved.png[,700,align=left] - -NOTE: When you hover the mouse over this row, an *Edit* button appears, where you can make updates to the definition. - -== DocID with regexp in Type Mappings - -“Doc ID with regexp” is another way the search service allows the user to extract “type identifiers” for indexing. - -* Set up a valid regular expression within docid_regexp. Remember this will be applied on the document IDs. -* Choose a type mapping name that is considered a match for the regexp. -* The type mapping name CANNOT be a regexp. - -For example, while working with the `travel-sample` bucket, set up docid_regexp to `air[a-z]{4}` and use the following type mappings. -* airline -* airport - -Below is a full index definition using it. -[source, json] ----- -{ - "name": "airline-airport-index", - "type": "fulltext-index", - "params": { - "doc_config": { - "docid_prefix_delim": "", - "docid_regexp": "air[a-z]{4}", - "mode": "docid_regexp", - "type_field": "type" - }, - "mapping": { - "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": { - "airline": { - "dynamic": true, - "enabled": true - }, - "airport": { - "dynamic": true, - "enabled": true - } - } - }, - "store": { - "indexType": "scorch", - "segmentVersion": 15 - } - }, - "sourceType": "gocbcore", - "sourceName": "travel-sample", - "sourceParams": {}, - "planParams": { - "indexPartitions": 1 - } -} ----- - -So setting this as the index definition would index all attributes of documents with “airline” or "airport" in its document IDs. - -image::fts-type-mapping-regexp-with-docid.png[,550,align=left] - -Note: The golang regexp support is based on -xref:https://github.com/google/re2/wiki/Syntax[Access the github link]