---
title: Run Queries with Edge Server
description: You can run SQL++ queries in a keyspace using the keyspace's query endpoint.
pubDate: 2026-08-17T09:53:44.266Z
antora:
  editUrl: https://github.com/couchbaselabs/docs-couchbase-lite-edge-server/edit/release/1.1/modules/rest-based-access/pages/queries-api.adoc
  xref: xref:couchbase-edge-server:rest-based-access:queries-api.adoc[]
---

[Consult the llms.txt file for a full list of contents](/llms.txt)
[View original HTML](/couchbase-edge-server/current/rest-based-access/queries-api.html)

# Run Queries with Edge Server

> 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](#named)
* [Ad-Hoc Queries](#adhoc)

## [](#named)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.

### [](#named-create)Create Named Queries

To create named queries for a database:

1. In the [databases](../configuration/edge-server-configuration.md#databases) section of the config file, add a [queries](../configuration/edge-server-configuration.md#databases-{DatabaseName}-queries) object to the database against which you want to run the query.
2. Within the [queries](../configuration/edge-server-configuration.md#databases-{DatabaseName}-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.

### [](#named-run)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](../configuration/edge-server-configuration.md#databases-{DatabaseName}-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.

> [!NOTE]
> If the database configuration does not include a `queries` section, a 403 Forbidden status is returned.

### [](#named-examples)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
"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
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
[
  {
    "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
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
[
  {
    "docId": "airport_4340"
  },
  {
    "docId": "airport_1254"
  },
  // ...
]
```

## [](#adhoc)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.

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

### [](#adhoc-enable)Enable Ad-Hoc Queries

To enable ad-hoc queries for a database:

* In the [databases](../configuration/edge-server-configuration.md#databases) section of the config file, add `"enable_adhoc_queries": true` to the database where you want to run the query.

### [](#adhoc-run)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.

> [!NOTE]
> If the database configuration does not include [enable\_adhoc\_queries](../configuration/edge-server-configuration.md#databases-{DatabaseName}-enable%5Fadhoc%5Fqueries), a 403 Forbidden status is returned.

### [](#adhoc-examples)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
"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
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
[
  {
    "_": {
      "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)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](../../../couchbase-lite/current/c/query-n1ql-mobile.md#query-format). There you will find links to other resources to learn more about SQL++.

## [](#see-also)See Also

* [Edge Server REST API](rest-api-landing.md)
* [Get Started with the Edge Server REST API](rest-api-start.md)
* [Database Operations with Edge Server](database-operations.md)
* [Document Access with Edge Server](document-access.md)
* [Monitor Changes with Edge Server](changes-feed.md)
* [Manage Replication with Edge Server](replication.md)
* [Edge Server Public REST API](../public-api-reference/index.md)