Send Feedback
Skip to content

Get Started with the DB Service in KDB-X

This page provides a quick introduction to installing and using the KDB-X DB Service.

Prerequisites

Before starting the DB Service, you must have your local environment ready. Ensure the following:

  • License. You have a valid KDB-X license. Set in the .env file. If it is a community edition license it should be assigned to KDB_LICENSE_B64. For a k4 license, use KDB_K4LICENSE_B64.

  • Docker, with docker compose available. Refer to the Docker installation guide and the docker compose installation instructions.

  • KDB-X installed, if you'd like to interact with the service via q. Refer to the KDB-X installation guide for instructions

Start the DB Service

The DB Service runs as a containerized service and is distributed using Docker Compose.

To start the DB service:

  1. Clone the DB-Service Github repo.

  2. Log in to the KX docker registry. If you don't already have an account, you can sign up for free at the KX Developer Center. A token can be created at https://portal.dl.kx.com/auth/token, if you need to generate a new one.

    EMAIL=email@example.com
BEARER=BEARERTOKEN
docker login -u $EMAIL -p $BEARER portal.dl.kx.com

  3. Run the initialization script:

    ./init-db.sh

  4. Start the service:

    docker compose up -d

Once the DB Service is running, you can use one of the connection methods below and try importing and querying some data.

Connect to the DB Service

You can connect to the DB Service using one of the following interfaces:

  • The REST API, using direct HTTP requests.
  • A q client, which wraps the REST API for use in q.
  • A Python client, which wraps the REST API for use in Python.

Select the appropriate tab for the interface you're using:

dbservice_client.q is included in the DB Service repo. Install it to your KDB-X module path, by default `$HOME/.kx/mod/kx:

cp dbservice_client.q ~/.kx/mod/kx/

Start q and load the client:

/ Load module
dbs:use`kx.dbservice_client

/ Create a session (default endpoint: http://localhost:8080)
session:dbs.createSession[]

/ Or specify an endpoint explicitly
session:dbs.createSession["localhost:8080"]

For usage examples and further details, refer to the q client documentation.

  1. Install the Python client:

    pip install --pre --extra-index-url https://portal.dl.kx.com/assets/pypi/ kdbx_db_service_client

    For KDB-X Python installation and environment setup, refer to the KDB-X Python install guide.

  2. Create a session to connect to the DB Service:

    import dbservice_client as dbs
session = dbs.Session()

    For non-default endpoints, transport-specific behavior, and examples, refer to the Python client documentation.

You can interact with the DB Service using HTTP requests.

Send requests to the service endpoint on port 8080. For example:

curl -X GET "http://localhost:8080/api/v0/tables"

For full request and response examples, refer to the OpenAPI documentation.

Import sample data

The init-db.sh copies sample data files to the imports staging directory. If you'd like to use your own data, copy it to the data/imports/ folder to make it available to the DB Service. All import paths are relative to the service.

Run the import using one of the supported clients. The example below imports the file fxquote.csv.gz into the fxquote table, which is dynamically created during the import as specified with the createTable flag.

Request

session.importFiles[`table`path`createTable!("fxquote";"fxquote.csv.gz";1b)]

Response

name    | "1d2c6754-1bf8-33a8-8df6-87dc34de40c2"
pipeline| ""
database| "db"
updtype | "ingest"
status  | "pending"
details | ()
tbls    | ()
dates   | ()
progress| `cmdCurrent`cmdIndex`cmdTotal`subCurrent`subIndex`subTotal!("";0n;0n;"";0n;0n)
error   | ""
warnings| ()
updated | "2026-04-27T11:36:26.012305327"

Request

session.import_files(table="fxquote", path="fxquote.csv.gz", createTable=True)

Response

{
  'name': 'b341fb2b-f8ba-4a7e-8b4f-2985ca100ef5',
  'pipeline': '',
  'database': 'db',
  'updtype': 'ingest',
  'status': 'pending',
  'details': [],
  'tbls': [],
  'dates': [],
  'progress': {'cmdCurrent': '',
    'cmdIndex': None,
    'cmdTotal': None,
    'subCurrent': '',
    'subIndex': None,
    'subTotal': None},
  'error': '',
  'warnings': [],
  'updated': '2026-04-27T11:29:38.101833268'
}

Request

curl -s -X POST "http://localhost:8080/api/v1/imports/files" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"table": "fxquote", 
       "path": 
       "fxquote.csv.gz", 
       "createTable": true}'

Response

{
  "name": "27454312-3653-8e62-ded7-8b563a409be6",
  "pipeline": "",
  "database": "db",
  "updtype": "ingest",
  "status": "pending",
  "details": [],
  "tbls": [],
  "dates": [],
  "progress": {
    "cmdCurrent": "",
    "cmdIndex": null,
    "cmdTotal": null,
    "subCurrent": "",
    "subIndex": null,
    "subTotal": null
  },
  "error": "",
  "warnings": [],
  "updated": "2026-04-27T09:48:53.806943488"
}

Query the data

After the import completes, run a query to retrieve data from the quote table.

The following examples retrieve rows:

  • between 2026-01-21 and 2026-01-22
  • where the symbol (sym) is AAPL

Run one of the following examples using your preferred client.

Request

session.querySimple[`table`startTS`endTS`sortCols`limit!(`fxquote;2026.03.02D;2026.03.03D;enlist "ts"; 5)]

Response

trddate    ts                            sym      bid     ask
-----------------------------------------------------------------
2026.03.02 2026.03.02D00:00:00.000000000 "AUDUSD" 0.67091 0.67094
2026.03.02 2026.03.02D00:00:00.000000000 "EURUSD" 1.16397 1.16399
2026.03.02 2026.03.02D00:00:00.000000000 "GBPUSD" 1.3419  1.34194
2026.03.02 2026.03.02D00:00:00.000000000 "USDCAD" 1.38744 1.3875
2026.03.02 2026.03.02D00:00:00.000000000 "USDJPY" 158.162 158.167

Request

session.query_simple(
    table="fxquote",
    startTS="2026.03.02D00:00:00.000",
    endTS="2026.03.03D00:00:00.000",
    sortCols=["ts"],
    limit=5,
    return_as="json",
)

Response

[
  {'trddate': '2026-03-02',
    'ts': '2026-03-02T00:00:00.000000000',
    'sym': 'AUDUSD',
    'bid': 0.67091,
    'ask': 0.67094},
  {'trddate': '2026-03-02',
    'ts': '2026-03-02T00:00:00.000000000',
    'sym': 'EURUSD',
    'bid': 1.16397,
    'ask': 1.16399},
  {'trddate': '2026-03-02',
    'ts': '2026-03-02T00:00:00.000000000',
    'sym': 'GBPUSD',
    'bid': 1.3419,
    'ask': 1.34194},
  {'trddate': '2026-03-02',
    'ts': '2026-03-02T00:00:00.000000000',
    'sym': 'USDCAD',
    'bid': 1.38744,
    'ask': 1.3875},
  {'trddate': '2026-03-02',
    'ts': '2026-03-02T00:00:00.000000000',
    'sym': 'USDJPY',
    'bid': 158.162,
    'ask': 158.167}
]

Request

curl -s -X POST "http://localhost:8080/api/v1/query/simple" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"table": "fxquote", 
      "startTS": 
      "2026.03.02D00:00:00", 
      "endTS": "2026.03.03D00:00:00", 
      "limit": 2}'

Response

{
  "header": {
    "corr": "43bb92c3-2d55-488c-8a38-adbf04e3f506",
    "logCorr": "43bb92c3-2d55-488c-8a38-adbf04e3f506",
    "version": 1,
    "rcvTS": "2026-04-27T09:53:17.384000000",
    "http": "json",
    "api": ".query.simple",
    "agg": ":172.20.0.7:5060",
    "refVintage": -9223372036854775807,
    "rc": 0,
    "ac": 0,
    "ai": "",
    "limitApplied": true
  },
  "payload": [
    {
      "trddate": "2026-03-02",
      "ts": "2026-03-02T00:00:00.000000000",
      "sym": "AUDUSD",
      "bid": 0.67091,
      "ask": 0.67094
    },
    {
      "trddate": "2026-03-02",
      "ts": "2026-03-02T00:00:06.000000000",
      "sym": "AUDUSD",
      "bid": 0.67095,
      "ask": 0.67097
    }
  ]
}

Reset the service

Important

Resetting the service permenantly deletes all data and RT client logs, and re-initializes directories.

If you need to reset the database, run:

  docker compose down 
  ./reset-db.sh

Next steps