Kùzu API Server

REST-style API server for the Kùzu graph database powered by Express.js.

Get started

Kùzu API Server is launched as a Docker container. Please refer to the Docker documentation for details on how to install and use Docker.

To access an existing Kùzu database, you can mount its path to the /database directory as follows:

docker run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database \
           -e KUZU_FILE={database file name} \
           --rm kuzudb/api-server:latest

By mounting local database files to Docker via -v {path to the directory containing the database file}:/database and -e KUZU_FILE={database file name}, the changes done through the API server will persist to the local database files after the server is shutdown. If the directory is mounted but the KUZU_FILE environment variable is not set, the API server will look for a file named database.kz in the mounted directory or create a new database file named database.kz in the mounted directory if it does not exist.

The --rm flag tells docker that the container should automatically be removed after we close docker.

If the launching is successful, you should see the logs similar to the following in your shell:

[00:46:50.833] INFO (1): Access mode: READ_WRITE
[00:46:50.834] INFO (1): CORS enabled for all origins
[00:46:50.853] INFO (1): Version of Kùzu: 0.3.1
[00:46:50.854] INFO (1): Deployed server started on port: 8000

Additional launch configurations

Access mode

By default, the API server is launched in read-write mode, which means that you can modify the database. If you want to launch it in read-only mode, you can do so by setting the MODE environment variable to READ_ONLY as follows.

docker run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database \
           -e KUZU_FILE={database file name} \
           -e MODE=READ_ONLY \
           --rm kuzudb/api-server:latest

The API server will then be launched in read-only mode, and you will see the following log message:

[00:46:50.833] INFO (1): Access mode: READ_ONLY

In read-only mode, you can still issue read queries, but you cannot run write queries or modify the schema.

Buffer pool size

By default, the API server is launched with a maximum buffer pool size of 80% of the available memory. If you want to launch API server with a different buffer pool size, you can do so by setting the KUZU_BUFFER_POOL_SIZE environment variable to the desired value in bytes as follows.

For example, to launch the API server with a buffer pool size of 1GB, you can run the following command.

docker run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database \
           -e KUZU_FILE={database file name} \
           -e KUZU_BUFFER_POOL_SIZE=1073741824 \
           --rm kuzudb/api-server:latest

Cross-Origin Resource Sharing (CORS)

By default, the API server is launched with CORS enabled for all origins. If you want to disable CORS, you can do so by setting the CROSS_ORIGIN environment variable to false as follows.

docker run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database \
           -e KUZU_FILE={database file name} \
           -e CROSS_ORIGIN=false \
           --rm kuzudb/api-server:latest

Launch with Podman

If you are using Podman instead of Docker, you can launch the API server by replacing docker with podman in the commands above. However, note that by default Podman maps the default user account to the root user in the container. This may cause permission issues when mounting local database files to the container. To avoid this, you can use the --userns=keep-id flag to keep the user ID of the current user inside the container, or enable :U option for each volume to change the owner and group of the source volume to the current user.

For example:

podman run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database:U \
           -e KUZU_FILE={database file name} \
           --rm kuzudb/api-server:latest

or,

podman run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database \
           -e KUZU_FILE={database file name} \
           --userns=keep-id \
           --rm kuzudb/api-server:latest

Please refer to the official Podman docs for mounting external volumes and user namespace mode for more information.

API endpoints

The Kùzu API server provides the following endpoints:

GET /:

Get the status of the server.

Example usage:

With fetch in JavaScript:

fetch("http://localhost:8000")
  .then((response) => response.json())
  .then((data) => console.log(data));

With curl in the terminal:

curl http://localhost:8000

With request in Python:

import requests
response = requests.get("http://localhost:8000")
print(response.json())

Example response:

{
  "status": "ok",
  "version": "0.3.1",
  "mode": "READ_WRITE"
}

GET /schema:

Get the schema of the database.

Example usage:

With fetch in JavaScript:

fetch("http://localhost:8000/schema")
  .then((response) => response.json())
  .then((data) => console.log(data));

With curl in the terminal:

curl http://localhost:8000/schema

With request in Python:

import requests
response = requests.get("http://localhost:8000/schema")
print(response.json())

Example response:

{
  "nodeTables": [
    {
      "name": "City",
      "comment": "",
      "properties": [
        {
          "name": "name",
          "type": "STRING",
          "isPrimaryKey": true
        },
        {
          "name": "population",
          "type": "INT64",
          "isPrimaryKey": false
        }
      ]
    },
    {
      "name": "User",
      "comment": "",
      "properties": [
        {
          "name": "name",
          "type": "STRING",
          "isPrimaryKey": true
        },
        {
          "name": "age",
          "type": "INT64",
          "isPrimaryKey": false
        }
      ]
    }
  ],
  "relTables": [
    {
      "name": "Follows",
      "comment": "",
      "properties": [
        {
          "name": "since",
          "type": "INT64"
        }
      ],
      "src": "User",
      "dst": "User"
    },
    {
      "name": "LivesIn",
      "comment": "",
      "properties": [],
      "src": "User",
      "dst": "City"
    }
  ],
  "relGroups": [],
  "rdf": []
}

POST /cypher:

Execute a Cypher query and get the result. The request body should be a JSON object with a query field containing the Cypher query and an optional params field containing the parameters for the query (if the query is a parameterized query / prepared statement).

Example usage:

With fetch in JavaScript:

fetch("http://localhost:8000/cypher", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "MATCH (u:User) WHERE u.age > $a RETURN u",
    params: {
      a: 20,
    },
  }),
})
  .then((response) => response.text())
  .then((data) => console.log(data));

With curl in the terminal:

curl -X POST\
     -H "Content-Type: application/json" \
     -d '{"query":"MATCH (u:User) WHERE u.age > $a RETURN u","params":{"a":25}}' \
     http://localhost:8000/cypher

With request in Python:

import requests
response = requests.post("http://localhost:8000/cypher", \
                         json={
                          "query": "MATCH (u:User) WHERE u.age > $a RETURN u",
                          "params": {"a": 25}
                          }
                        )
print(response.json())

Example response:

{
  "rows": [
    {
      "u": {
        "name": "Adam",
        "age": 30,
        "_label": "User",
        "_id": { "offset": 0, "table": 0 }
      }
    },
    {
      "u": {
        "name": "Karissa",
        "age": 40,
        "_label": "User",
        "_id": { "offset": 1, "table": 0 }
      }
    },
    {
      "u": {
        "name": "Zhang",
        "age": 50,
        "_label": "User",
        "_id": { "offset": 2, "table": 0 }
      }
    }
  ],
  "dataTypes": { "u": "NODE" },
  "isSchemaChanged": false
}

Deployment

A GitHub actions pipeline has been configured to automatically build and deploy the Docker image to Docker Hub upon pushing to the master branch. The pipeline will build images for both amd64 and arm64 platforms.

Contributing

We welcome contributions to Kùzu API Server. By contributing to Kùzu API Server, you agree that your contributions will be licensed under the MIT License.