Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

USE Clause

  • reference
March 23, 2025
+ 12
The USE clause enables you to specify that the query should use particular keys, or a particular index.

Purpose

The USE clause is used within the FROM clause. It enables you to provide a hint to the query service, specifying that the query should use particular keys, or a particular index.

Prerequisites

For you to select data from a document or keyspace, you must have the query_select privilege on the document or keyspace. For more details about user roles, see Authorization.

Syntax

use-clause ::= use-keys-clause | use-index-clause
use clause

USE KEYS Clause

Purpose

You can refer to a document’s unique document key by using the USE KEYS clause. Only documents having those document keys will be included as inputs to a query.

Syntax

use-keys-clause ::= USE use-keys-term
use keys clause 
use-keys-term ::= [ PRIMARY ] KEYS expr
use keys term
PRIMARY KEYS

USE KEYS and USE PRIMARY KEYS are synonyms.

Arguments

expr

String of a document key or an array of comma-separated document keys.

Examples

Example 1. Select a single document by its document key
N1QL
Copy
SELECT *
FROM `travel-sample`.inventory.airport
USE KEYS "airport_1254";
Results
JSON
Copy
[
  {
    "travel-sample": {
      "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"
    }
  }
]
Example 2. Select multiple documents by their document keys
N1QL
Copy
SELECT *
FROM `travel-sample`.inventory.airport
USE KEYS ["airport_1254","airport_1255"];
Results
JSON
Copy
[
  {
    "travel-sample": {
      "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"
    }
  },
  {
    "travel-sample": {
      "airportname": "Peronne St Quentin",
      "city": "Peronne",
      "country": "France",
      "faa": null,
      "geo": {
        "alt": 295,
        "lat": 49.868547,
        "lon": 3.029578
      },
      "icao": "LFAG",
      "id": 1255,
      "type": "airport",
      "tz": "Europe/Paris"
    }
  }
]

USE INDEX clause

Purpose

Use the USE INDEX clause to specify the index or indexes to be used as part of the query execution. The query engine attempts to use a specified index if the index is applicable for the query.

In Couchbase Server 6.6 and later, you can omit the index name and just specify the index type. In this case, the query service considers all the available indexes of the specified type.

If you attempt to use an index which is still scheduled for background creation, the request fails.

Syntax

use-index-clause ::= USE use-index-term
use index clause 
use-index-term ::= INDEX '(' index-ref [ ',' index-ref ]* ')'
use index term 
index-ref ::= [ index-name ] [ index-type ]
index ref

Arguments

index-name

[Optional] String or expression representing an index to be used for the query.

This argument is optional; if omitted, the query engine considers all available indexes of the specified index type.

USING clause

index-type ::= USING ( GSI | FTS )
'USING' ( 'GSI' | 'FTS' )

Specifies which index form to use.

USING GSI

A Global Secondary Index, which lives on an index node and can possibly be separate from a data node.

USING FTS

A Full Text Search index, for use with queries containing Search functions. In Couchbase Server 6.6 Enterprise Edition and later, you can use this hint to specify that the query is a Flex Index query using a Full Text Search index. In Couchbase Server 6.6 Community Edition and later, this hint is ignored if the query does not contain a Search function.

This clause is optional; if omitted, the default is USING GSI.

Examples

Example 3. Use a specified Global Secondary Index

Create an index of airlines and destination airports, and then use it in a query for flights originating in San Francisco.

n1ql
ViewCopy
CREATE INDEX idx_destinations
ON `travel-sample`.inventory.route (airlineid, airline, destinationairport);
n1ql
ViewCopy
SELECT airlineid, airline, sourceairport, destinationairport
FROM `travel-sample`.inventory.route USE INDEX (idx_destinations USING GSI)
WHERE sourceairport = "SFO";
Example 4. Use any suitable Full Text Search index

Specify that the query service should prefer an FTS index, without specifying the index by name. To qualify for this query, there must be an FTS index on state and type, using the keyword analyzer. (Or alternatively, an FTS index on state, with a custom type mapping on "hotel".)

n1ql
Copy
SELECT META().id
FROM `travel-sample`.inventory.hotel USE INDEX (USING FTS)
WHERE state = "Corse" OR state = "California";

All FTS indexes are considered. If a qualified FTS index is available, it is selected for the query. If none of the available FTS indexes are qualified, the available GSI indexes are considered instead.