# Querying kdb+ data

_This page introduces the three things you need to query a kdb+ database: an endpoint to connect to, a tool to send the query from, and a query language to express it in._

To query a kdb+ database, you need:

1. an [endpoint](#endpoint) - a q process that holds the data and listens for requests
1. a [client tool](#client-tools) - the program you send the query from and view the result in
1. a [query language](#query-language) - typically qSQL, or a call to a function defined on the server

If the data is already in your local q process, you don't need an endpoint or a client: type the query at the q prompt. A client tool can still be useful, for example an IDE to edit queries and browse the results.

The examples on this page query a database of US equity trades and quotes. To build it, generate eight trading days of data into `/tmp/testdb` with the [datagen module](../../modules/datagen/overview.md):
```q
q)([getInMemoryTables; buildPersistedDB]): use `kx.datagen.capmkts
q)buildPersistedDB["/tmp/testdb"; ([start: 2026.04.01; end: 2026.04.10])]
```

Start a q process that loads the database and listens on port 5100:
```bash
q /tmp/testdb -p 5100
```

## Endpoint

An endpoint is the host and port of a q process that [listens on a port](../io_and_communication/listening-port.md). The same port can accept several kinds of connection:

- **q IPC** - the native binary protocol, used by q, KDB-X Python, IDEs, and the client libraries. It's the fastest way to move data, because results travel in kdb+ format without conversion. See [IPC basics](../io_and_communication/basics.md).
- **HTTP** - text requests from a browser, `curl`, or any HTTP client. See [HTTP](../io_and_communication/http.md).
- **WebSocket** - a persistent, full-duplex connection, commonly used by browser applications for streaming queries and updates. See [WebSockets](../io_and_communication/websockets.md).

In production, clients often connect to a [gateway](../manage_streaming_data/gateway-design/index.md) rather than to the process that holds the data. The gateway routes each query to the right processes and combines the results.

## Client tools

Pick a tool based on what you want to do with the result.

### Another q process on your local computer

Open a handle to the endpoint and send a synchronous request. The result comes back as a q object, ready for further processing:
```q
q)h:hopen `:localhost:5100  / or simply: hopen 5100
q)h "select from trade where date=last date, i<3"
date       sym  time                 price  size stop cond ex
-------------------------------------------------------------
2026.04.10 AAPL 0D09:30:00.207601090 307.12 84   0    C    X
2026.04.10 AAPL 0D09:30:00.631051656 307.15 68   0    X    D
2026.04.10 AAPL 0D09:30:00.719172601 307.16 64   1    H    S
```

This is how q processes in a distributed system talk to each other. See [IPC basics](../io_and_communication/basics.md) and [asynchronous communication](../io_and_communication/async.md).

### Browser or curl

The built-in web server answers HTTP requests without extra software, which suits ad-hoc queries. Put the query after `?` in the URL, and choose the response format with the path, for example `.txt`, `.csv` or `.json`:
```bash
$ curl --variable 'q=select max price by sym from trade where date=2026.04.10, sym in `AAPL`MSFT' \
    --expand-url 'http://localhost:5100/.csv?{{q:url}}'
sym,price
AAPL,312.43
MSFT,576.7
```

The query must be URL-encoded. Here `--variable` (curl 8.3 or later) stores the query in the curl variable `q`, and `{{q:url}}` inserts it into the URL with spaces and special characters encoded, so the query stays readable.

> **Warning — Don't use `--data-urlencode`**
>
>
> `curl -G --data-urlencode` encodes spaces as `+`, which the default q HTTP handler doesn't decode, so the query fails with a `'+` error.
>
If the server exposes a REST API, call its endpoints in the same way. See [HTTP](../io_and_communication/http.md) to customize the request handlers and secure access.

> **Warning — Secure query endpoints**
>
>
> The default HTTP and IPC handlers can evaluate query text. Don't expose them to untrusted clients. In production, authenticate connections and restrict requests to an allowlist of server-defined functions; see [Security and management](../io_and_communication/security.md).
>
### IDE

An IDE designed for kdb+ lets you write queries, run them against a connection, and explore the result. Results are typically tables, and the IDE lets you sort by a column and filter rows by value without writing more q.

- [KX extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=KX.kdb) - syntax highlighting, code completion, connection management, and a results grid.
- [KX Developer](https://code.kx.com/developer/) - a browser-based IDE for q.

### Jupyter notebook and KDB-X Python

[KDB-X Python](https://code.kx.com/pykx/) lets you query kdb+ from Python and convert results to pandas, PyArrow, NumPy, or native Python objects. Use it in a Jupyter notebook to combine kdb+ queries with Python analytics and plotting.

### KX Dashboards

[KX Dashboards](../../integrations/dashboards.md) builds interactive, feature-rich dashboards on top of kdb+ queries, with real-time updates, charts, grids, and drill-downs. Use it to share analysis with users who don't write q.

## Query language

Whatever the tool, the server evaluates the request and returns the result. The request is typically either a function call or a qSQL statement.

### Function call

A function defined on the server, also called a user-defined function (UDF), stored procedure or API, hides the query logic behind a name and a parameter list. For example, the server defines `vwap` to return the volume-weighted average price of some stocks on a given date:
```q
q)vwap:{[d;s] select vwap:size wavg price by sym from trade where date=d, sym in s}
```

Clients call it by sending the function name and arguments as a list rather than as a string:
```q
q)h (`vwap; 2026.04.10; `AAPL`MSFT)
sym | vwap
----| --------
AAPL| 304.9213
MSFT| 561.6922
```

Function calls are the preferred way to expose data in production:

- The server controls which queries clients can run, so you can apply [access control](../io_and_communication/security.md).
- Arguments travel as typed q values, so you avoid building query strings and the injection risks that come with them.
- You can change or optimize the implementation without changing the clients.

These benefits depend on server-side enforcement. Configure the message handlers to reject arbitrary query strings and dispatch only the functions each client is allowed to call.

### qSQL

For ad-hoc analysis, write a qSQL statement. qSQL has a syntax similar to SQL and works on both in-memory and on-disk tables. There are four qSQL statements:

[`select`](select.md)

: Returns a table: a subset of rows and columns, new computed columns, or aggregations. It's the statement you'll use most often. On a partitioned table, put the partition column (here `date`) first in the `where` clause so that q reads only the partitions it needs.
    ```q
    q)select n:count i, avgPrice:avg price by sym from trade where date=2026.04.10, sym in `AAPL`MSFT
    sym | n    avgPrice
    ----| -------------
    AAPL| 1048 304.9977
    MSFT| 979  561.811
    ```

[`update`](exec-update-delete.md#update)

: Adds new columns or overwrites existing ones. On a table mapped from disk, `update` returns a modified copy in memory and leaves the files unchanged.
    ```q
    q)3#update range:high-low from daily
    date       sym  open   high   low    close  price       size  range
    -------------------------------------------------------------------
    2026.04.01 AAPL 254.96 277.22 253.52 276.85 1.36267e+07 50863 23.7
    2026.04.01 AGEN 3.99   4.22   3.9    4.21   213204.7    52955 0.32
    2026.04.01 AIG  79.8   82.58  78.75  82.19  4119636     51239 3.83
    ```

[`delete`](exec-update-delete.md#delete)

: Removes rows or columns. Like `update`, it returns a copy in memory, so the table on disk keeps all its rows:
    ```q
    q)count delete from daily where date<2026.04.10
    51
    q)count daily
    408
    ```

[`exec`](exec-update-delete.md#exec)

: Returns its result in whatever shape the expression produces (a list, a dictionary, or an atom) rather than always a table. Use it for advanced cases, such as feeding a result directly into further q code.
    ```q
    q)exec sym!close from daily where date=2026.04.10, sym in `AAPL`MSFT
    AAPL| 300.78
    MSFT| 564.14
    q)exec max high from daily where sym=`AAPL
    322.98
    ```

> **Note — Partitioned tables**
>
>
> On a partitioned table such as `trade`, only `select` runs directly. `update` and `delete` signal a `par` error, and `exec` signals `nyi`. Select the rows you need first, then apply the other statement to the result in memory:
>
> ```q
> q)exec avg price by sym from select from trade where date=2026.04.10, sym in `AAPL`MSFT
> AAPL| 304.9977
> MSFT| 561.811
> ```
>
> To change the data on disk itself, see [database maintenance](../interact_with_databases/maintenance.md).
>
> **Tip — Prefer SQL?**
>
>
> KDB-X also accepts [SQL](../../integrations/sql/introduction.md) queries, and clients that speak the PostgreSQL protocol can connect through [PG Wire](../../integrations/pgwire/introduction.md).
>
## Next steps

- [How to select data](select.md) - choose columns, filter, group, sort, and keep queries fast, on in-memory and on-disk tables
- [Joins](../../ref/joins.md) - combine rows from two tables, including as-of and window joins for time-series data
- [Functional qSQL](../../ref/funsql.md) - construct queries when column names, filters, or grouping are chosen at runtime
