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.

Run Queries with Edge Server

    March 23, 2025
    + 12
    You can run SQL++ queries in a keyspace using the keyspace’s query endpoint.

    With Edge Server, you can specify SQL++ queries in two ways.

    Named Queries

    A named query is predefined in the Edge Server config file. A client may run the query by specifying the query name. Each named query is associated with one of the databases defined by the config file. You can specify one or more named query for each database.

    Create Named Queries

    To create named queries for a database:

    1. In the databases section of the config file, add a queries object to the database against which you want to run the query.

    2. Within the queries object, create a key-value pair for each named query that you want to define. For each key-value pair, the key should be the name of the query, and the value should be a string containing the query text.

    Run a Named Query

    To run a named query:

    1. Make a GET or POST call to the _query endpoint for the keyspace where the query is defined.

    2. Specify the query name as a path parameter. The name must match one of the keys of the database configuration’s queries object.

    3. To pass parameters to the query, specify them as query parameters for a GET REST API call, or as a JSON object in the request body for a POST REST API call. Specify the query parameter names without the initial $.

    If the query is successful, the response is a JSON array of objects. Each object is a result; the keys are the column names.

    If the database configuration does not include a queries section, a 403 Forbidden status is returned.

    Named Query Examples

    In the command line examples:

    • $USER and $PASSWORD are the credentials for Couchbase Edge Server.

    • $CERT is the name and path to a TLS certificate file, for example cert.cer.

    • $HOST and $PORT are the host and port to connect to Couchbase Edge Server, for example localhost:59840.

    Note that the following cURL examples use a self-signed TLS server certificate. In production, you are strongly recommended to use a TLS certificate generated by a well-known authority.

    Example 1. Specify a named query

    The following configuration file extract specifies a query named querydocsoftype in the travel-sample database. The query expects a parameter called $type.

    json
    Copy
    "databases": {
    "travel-sample":
    {
        // ...
        "queries": {
            "querydocsoftype": "SELECT META().id AS docId FROM _ WHERE type = $type"
        }
    }
},
// ...
    Example 2. Run a named query with a GET request

    The following request runs the query named querydocsoftype in the travel-sample.inventory.airport keyspace. The query parameter specifies a value for the $type parameter.

    HTTP Request
    sh
    Copy
    curl -XGET --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport/_query/querydocsoftype?type=airport"

    The response is a list of document IDs. The example below is truncated to save space.

    HTTP Response
    json
    Copy
    [
  {
    "docId": "airport_4340"
  },
  {
    "docId": "airport_1254"
  },
  // ...
]
    Example 3. Run a named query with a POST request

    The following request runs the query named querydocsoftype in the travel-sample.inventory.airport keyspace. The request body specifies a value for the $type parameter.

    HTTP Request
    sh
    Copy
    curl -XPOST --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport/_query/querydocsoftype" \
  --json '{"type": "airport"}'

    Again, the response is a list of document IDs. The example below is truncated to save space.

    HTTP Response
    json
    Copy
    [
  {
    "docId": "airport_4340"
  },
  {
    "docId": "airport_1254"
  },
  // ...
]

    Ad-Hoc Queries

    An ad-hoc query is an arbitrary SQL++ query that the client specifies when running the query. You must enable ad-hoc queries in the Edge Server config file. You must enable ad-hoc queries for each database where you want to run an arbitrary query.

    Allowing clients to execute raw SQL++ queries introduces security risks, as malicious queries could cause denial of service.

    Enable Ad-Hoc Queries

    To enable ad-hoc queries for a database:

    • In the databases section of the config file, add "enable_adhoc_queries": true to the database where you want to run the query.

    Run an Ad-Hoc Query

    To run an ad-hoc query:

    1. Make a POST call to the _query endpoint for a keyspace where ad-hoc queries are permitted.

    2. Pass a JSON object as the request body. The JSON object must contain a query key, whose value is the SQL++ query string.

    3. To pass parameters to the query, add a parameters key to the request body. The value of this key must be an object mapping query parameter names to values. Specify the query parameter names without the initial $.

    If the query is successful, the response is a JSON array of objects. Each object is a result; the keys are the column names.

    If the database configuration does not include enable_adhoc_queries, a 403 Forbidden status is returned.

    Ad-Hoc Query Examples

    In the command line examples:

    • $USER and $PASSWORD are the credentials for Couchbase Edge Server.

    • $CERT is the name and path to a TLS certificate file, for example cert.cer.

    • $HOST and $PORT are the host and port to connect to Couchbase Edge Server, for example localhost:59840.

    Note that the following cURL examples use a self-signed TLS server certificate. In production, you are strongly recommended to use a TLS certificate generated by a well-known authority.

    Example 4. Enable ad-hoc queries

    The following configuration file extract enables ad-hoc queries in the travel-sample database.

    json
    Copy
    "databases": {
    "travel-sample":
    {
        // ...
        "enable_adhoc_queries": true
    }
},
// ...
    Example 5. Run an ad-hoc query

    The following request runs an ad-hoc query in the travel-sample.inventory.airport keyspace. The request body specifies the query.

    HTTP Request
    sh
    Copy
    curl -XPOST --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport/_query" \
  --json '{"query": "SELECT * FROM _ LIMIT 1"}'

    The query returns a single record from the keyspace.

    HTTP Response
    json
    Copy
    [
  {
    "_": {
      "id": 7630,
      "type": "airport",
      "country": "United States",
      "icao": "KMPI",
      "airportname": "MariposaYosemite",
      "city": "Mariposa",
      "faa": "MPI",
      "tz": "America/Los_Angeles",
      "geo": {
        "lat": 37.3039,
        "lon": -120.0222,
        "alt": 2454.0
      }
    }
  }
]

    The Query Language: SQL++

    Couchbase Edge Server uses a query language called SQL++ for Mobile.

    SQL++ is an expressive, powerful, and complete SQL dialect for querying, transforming, and manipulating JSON data. Because it’s based on SQL, it’s immediately familiar to developers, who can quickly start developing rich applications.

    SQL++ for Mobile is a Couchbase implementation of SQL++, focused on mobile and edge applications. As the name suggests, SQL++ for Mobile is used across the Couchbase Mobile product range.

    For details of the query language, see Query Format. There you will find links to other resources to learn more about SQL++.

    See Also