Classic Editor
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 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 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.
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 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.
-
Click the Add Index link in the upper right of the Couchbase Web Console > Search page.
-
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_geopoint as the name of the Search index you are creating in the Index Name text-box.
-
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.
-
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.
-
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 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 <bucket>._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 equivalent but on a per collections basis.
-
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.
-
Select _default from the Collection pull-down, note the pull down will change to a text field prefilled with _default._default
-
Leave the [ ] only index specified fields checkbox blank or unset.
This will index all fields in the scope _default collection _default, however not this is not recommended for large production datasets.
-
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.
-
A context menu of "insert child mapping" (for sub-objects) and "insert child field" (for properties) will appear.
-
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".
-
Set the text box field to geo, this will also update "searchable as" to geo.
-
Change the pull-down type to geopoint.
By configuring the child field information form, specifically identify the object geo as type geopoint this will tell the Search indexer to recognize top level sub-objects like:
"geo": { "lat": 53.48253, "lon": -2.23527, "accuracy": "ROOFTOP" },
-
Check [X] the boxes "store" and "include in _all field"
-
Click on the blue ok at the right of the section to save this sub-form.
-
-
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.
-
If you subsequently Edit your Index it should look like the following:
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. However this index can be edited and optimized if you check [X] only index specified fields under the Type Mappings section. This will result in a much smaller index and a faster index build since only the field geo will be indexed in the set of documents. |
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):
{ "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 of53.482358
. The target-fieldgeo
is specified, as is adistance
of100
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.
-
Verify you have some results
Advanced Index Settings and Other Features in the UI
The complete range of available options for creating Search indexes for any production environment is covered here: Creating Indexes.
Once you hit the Create Index button you will return to the Couchbase Web Console > Search page (note, if you tested any index just access the Couchbase Web Console > Search page again).
At this point, you are returned to the Full Text Search screen.
A new row now appears for the index you have just created. When left-clicked on, the row opens or expands as follows:
Index Build Progress
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.
Statistic: docs processed
The percentage figure appears under the indexing progress column and represents the number of documents present in the index.
-
On an initial build this may take a while to process all the documents.
-
A mutation to an existing document will not increment this count (unless new items are added).
Statistic: indexing progress
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 complete.
-
However, search queries will be allowed as soon as the index is created, meaning partial results can be expected until the index build is complete.
-
If later mutations com in the percentage may actually jump around as batches of documents are processed.
-
If one or more of the nodes in the cluster running data service goes down and/or are failed over, indexing progress may show a value > 100%.
Show Index Definition
This expandable section shows the JSON document that describes the current index configuration, as created by means of the user interface.
A checkbox [ ] Show curl command to modify this index definition is set will wrap the index definition with a command line cURL syntax.
You can copy either variant (the cURL mode) and the definitions can be used via the Search REST API or any Couchbase SDK.
Using the Index Definition Preview
The Index Definition Preview appears to the right-hand side of the Add Index (or an Edit Index) screen.
Following index-definition, the upper portion may appear as follows:
This preview (like the Show Index Definition JSON from the main Search page) consists of the JSON document that describes the current index configuration, as created by means of the user interface. By left-clicking on the copy to clipboard tab, the definition can be saved.
These definitions can be used via the Search REST API or any Couchbase SDK.
Advanced Index Configuration Options
The complete range of available options for creating Search indexes for any production environment is covered here: Creating Indexes.