lancedb/docs/web/sql/index.mdx

---
title: "SQL reference"
sidebarTitle: "Overview"
description: "The SQL surface: dialect, connecting a client, and a page per construct."
icon: table-list
keywords: ["sql", "datafusion", "flight sql", "reference", "dialect"]
---

<Badge color="red">Enterprise</Badge> SQL runs on a deployment. A local database
has no engine to plan a statement, so `execute_query` raises there -- see
[SQL](/basics/sql#sql-is-remote).

This is a reference rather than a guide: one page per construct, syntax first.
The guides elsewhere in these docs show the same operations from the SDKs.

## The dialect {#dialect}

LanceDB executes SQL with [Apache DataFusion](https://datafusion.apache.org),
currently **version 54**. The grammar, built-in functions and type system are
DataFusion's, so anything its reference documents for that version works here
unchanged and is not reproduced.

What these pages add is the part that is LanceDB's: how a query reaches the
engine, how Lance columns appear to it, and the statements a lakehouse needs
that DataFusion has no concept of.

## Connecting {#connecting}

SQL is served over an
[Arrow Flight SQL](https://arrow.apache.org/docs/format/FlightSql.html)
endpoint, so any Flight SQL client reaches it and results arrive as Arrow
record batches -- nothing is converted to pandas or Python objects unless you
ask.

From Python, the connection runs SQL directly, without a separate client:

```python
reader = db.execute_query("SELECT id, text FROM my_docs LIMIT 10")
table = reader.read_all()
```

`execute_query` hands back a reader as soon as the first batch is ready rather
than when the query finishes, so a large result set does not have to fit in
memory before you start reading it. See [Queries](/basics/query).

The TypeScript SDK has no SQL method; reach for a Flight SQL client instead --
and in Python, reach for one too when the caller is outside the SDK's own
process, such as a BI tool or a notebook in another language:

```bash
pip install flightsql-dbapi        # Python DB API 2 interface
npm install --save @lancedb/flightsql-client
```

<CodeGroup>
```python Python icon="python"
from flightsql import FlightSQLClient

client = FlightSQLClient(
    host="your-enterprise-endpoint",
    port=10025,
    insecure=True,
    token="DATABASE_TOKEN",
    metadata={"database": "your-project-slug"},
    features={"metadata-reflection": "true"},
)

info = client.execute("SELECT * FROM flights WHERE origin = 'SFO'")
ticket = info.endpoints[0].ticket
result = client.do_get(ticket).read_all()
```

```typescript TypeScript icon="square-js"
import { Client } from "@lancedb/flightsql-client";

const client = await Client.connect({
    host: "your-enterprise-endpoint:10025",
    username: "lancedb",
    password: "password",
});

const result = await client.query("SELECT * FROM flights WHERE origin = 'SFO'");
```
</CodeGroup>

## Usage {#usage}

The endpoint executes one statement per request and is meant for the queries
and DDL/DML pages below. Reach for the SDKs instead for table-management
operations that have no SQL form, such as building a vector index or a merge
insert -- see [What SQL cannot do](#cannot).

## Reference {#reference}

### DDL, by object {#ddl}

| | |
| --- | --- |
| [Namespace](/sql/ddl/namespace) | `CREATE SCHEMA`, `DROP SCHEMA` |
| [Table](/sql/ddl/table) | `CREATE`, `DESCRIBE`, `ALTER`, `CLONE`, `DROP TABLE` |
| [View](/sql/ddl/view) | `CREATE VIEW`, `DROP VIEW` |
| [Materialized view](/sql/ddl/materialized-view) | `CREATE MATERIALIZED VIEW`, `SHOW MATERIALIZED VIEWS` |
| [Index](/sql/ddl/index) | `CREATE INDEX`, `DROP INDEX` |
| [Function](/sql/ddl/function) | `CREATE FUNCTION`, `SHOW FUNCTIONS`, `DROP FUNCTION` |
| [Job](/sql/ddl/job) | `SHOW JOBS`, `SHOW ERRORS`, `PAUSE`/`RESUME`/`CANCEL JOB` |

### DML {#dml}

| | |
| --- | --- |
| [Insert](/sql/dml/insert) | `INSERT INTO`, including `INSERT ... SELECT` |
| [Update](/sql/dml/update) | `UPDATE ... SET` |
| [Delete](/sql/dml/delete) | `DELETE FROM` |
| [Copy](/sql/dml/copy) | `COPY INTO` / `COPY TO` |
| [Refresh](/sql/dml/refresh) | filling computed columns and materialized views |

### DQL {#dql}

| | |
| --- | --- |
| [Data types](/sql/data-types) | how Lance columns appear to SQL, and pseudo-columns |
| [Select](/sql/dql/select) | projection, filtering, ordering, set operations, CTEs |
| [Subqueries](/sql/dql/subqueries) | scalar, `IN`, `EXISTS`, correlated, derived tables |
| [Joins](/sql/dql/join) | inner, outer, cross, and namespace-qualified paths |
| [Aggregation](/sql/dql/aggregation) | `GROUP BY`, `HAVING`, the aggregate set |
| [Window functions](/sql/dql/window) | `OVER`, framing, ranking and offset functions |
| [Sampling](/sql/dql/sampling) | `TABLESAMPLE`, by rows or by fragments |
| [Full-Text Search](/sql/dql/fts) | the `fts()` table function, and its query forms |
| [Explain](/sql/dql/explain) | `EXPLAIN`, `EXPLAIN ANALYZE`, `EXPLAIN VERBOSE` |

### Expressions {#expressions}

| | |
| --- | --- |
| [Operators](/sql/operators) | comparison, logical, arithmetic, literals, precedence |
| [Functions](/sql/functions) | where to find each kind, and table functions |
| [Scalar functions](/sql/scalar-functions) | the per-row catalogue, and what Lance accelerates |
| [Prepared statements](/sql/prepared-statements) | planning once, executing many times |

## What SQL cannot do {#cannot}

| | |
| --- | --- |
| Vector search | no SQL form -- a query-builder operation |
| Merge insert | no SQL form -- needs a source relation and a per-match policy |
| `information_schema` | not enabled, so `SHOW TABLES` and `SHOW COLUMNS` fail |
| `PREPARE` / `EXECUTE` | preparation is a [protocol feature](/sql/prepared-statements), not a statement |
| Run on a local database | no engine to plan the statement |

See [Limits](/basics/limits#sql) for the bounds these pages enforce.