HTTP API​

Aliveness​

Check if your instance is alive.

http://<hostname>:<port>/server/status/alive

If your instance is alive, it will respond with a 200 status code and "OK" as the payload. Otherwise, it will respond with a 50x or a network error.

Readiness​

Check if your instance is ready to receive queries.

http://<hostname>:<port>/server/status/ready

If your instance is ready, it will respond with a 200 status code and "OK" as the payload. Otherwise, it will respond with a 50x or a network error.

Processes​

compiler_process_spawns_total

Counter. Total number of compiler processes spawned.

compiler_processes_current

Gauge. Current number of active compiler processes.

Backend connections and performance​

backend_connections_total

Counter. Total number of backend connections established.

backend_connections_current

Gauge. Current number of active backend connections.

backend_connection_establishment_errors_total

Counter. Number of times the server could not establish a backend connection.

backend_connection_establishment_latency

Histogram. Time it takes to establish a backend connection, in seconds.

backend_query_duration

Histogram. Time it takes to run a query on a backend connection, in seconds.

Client connections​

client_connections_total

Counter. Total number of clients.

client_connections_current

Gauge. Current number of active clients.

client_connections_idle_total

Counter. Total number of forcefully closed idle client connections.

Query compilation​

edgeql_query_compilations_total

Counter. Number of compiled/cached queries or scripts.

edgeql_query_compilation_duration

Histogram. Time it takes to compile an EdgeQL query or script, in seconds.

Errors​

background_errors_total

Counter. Number of unhandled errors in background server routines.

Making a query request​

Make a query to your EdgeDB database using this URL:

http://<hostname>:<port>/db/<database-name>/edgeql

You may make queries via either the POST or GET HTTP method. Query requests can take the following fields:

• query - contains the EdgeQL query string

• variables- contains a JSON object where the keys are the parameter names from the query and the values are the arguments to be used in this execution of the query.

When using the GET method, supply query and variables as query parameters. For a POST request, use the application/json content type and submit a JSON payload with query and variables as top-level keys in that payload as in this example:

Here’s an example query you might want to run to insert a new person in your database, as executed from the EdgeDB REPL:

db> 

insert Person { name := <str>$name };

Parameter <str>$name: Pat
{default::Person {id: e9009b00-8d4e-11ed-a556-c7b5bdd6cf7a}}

The query inserts a Person object. The object’s name value is parameterized in the query as $name.

This GET request would run the same query (assuming the instance is local and the database is named edgedb):

GET http://localhost:<port>/db/edgedb/edgeql?query=insert%20Person%20%7B%20name%20%3A%3D%20%3Cstr%3E$name%20%7D%3B&variables=%7B%22name%22%3A%20%22Pat%22%7D

As you can see with even this simple query, URL encoding can quickly become onerous with queries over GET.

Here’s the JSON payload of a POST request to execute the query:

{
  "query": "insert Person { name := <str>$name };",
  "variables": { "name": "Pat" }
}

Response​

The response format is the same for both methods. The body of the response is JSON of the following form:

{
  "data": [ ... ],
  "error": {
    "message": "Error message",
    "type": "ErrorType",
    "code": 123456
  }
}

The data response field will contain the response set serialized as a JSON array.

Note that the error field will only be present if an error actually occurred. The error will further contain the message field with the error message string, the type field with the name of the type of error and the code field with an integer error code.