A newer version of this documentation is available.

View Latest

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.

        fts search page
      • Click the Add Index link in the upper right of the Couchbase Web Console > Search page.

        fts add initial
      • 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.

        fts index name geopoint
      • 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.

        fts index name and bucket geopoint
      • 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.

        fts select geopoint scope collections
      • 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.

        fts uncheck default mapping
      • 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.

          fts index menu1 nondefault empty
        • Select _default from the Collection pull-down, note the pull down will change to a text field prefilled with _default._default

          fts index menu1 geopoint filled
        • 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.

          fts index menu1 geopoint hover
        • A context menu of "insert child mapping" (for sub-objects) and "insert child field" (for properties) will appear.

          fts index menu2 geopoint empty
        • 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".

          fts index menu2 geopoint filled
        • 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.

          fts index menu2 geopoint filled
      • 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.

        fts index create button
      • If you subsequently Edit your Index it should look like the following:

        fts edit index geopoint
      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 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.

        fts index geopoint search
      • Verify you have some results

        fts index geopoint search 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:

      fts new index progress

      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.

      fts show index definition

      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:

      fts index definition preview

      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.