mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-31 07:46:51 +00:00
Jack Ye
ddb318567a
## Summary - Complete the SQL reference: `ATTACH DATABASE`, the `CHANGES` clause, and `dedupe()`/`duplicate_pairs()` (verified against current sophon source; these were recently renamed from `vector_dedup`/`vector_duplicate_pairs`). Fix the blob-column default-projection claim and add the previously undocumented `blob_descriptor()`. - Enrich the gated Functions draft (still `.mintignore`'d, pre-release): chained Functions over blob outputs, GPU-produced blobs, Secrets, multi-input/output binding, `code=[module]` packaging. - Upgrade the materialized-view and computed-column auto-refresh drafts with precise, verified catch-up semantics, and add the missing `ALTER MATERIALIZED VIEW` / `CREATE ... WITH(...)` sections (also gated — the automatic-refresh scheduler is still dev/staging-only). - Thread one running example (video frames → GPU extract/caption → dedup → auto-refreshing materialized view) through Functions, materialized views, and the LeRobotDataset integration guide instead of a separate tutorial. - Rename "LanceDB OSS"/"OSS" to "LanceDB Embedded"/"Embedded" throughout (52 files); activate the existing availability-comparison mechanism on `basics/offerings.mdx` for a full feature-by-feature comparison table.
70 lines
2.5 KiB
Plaintext
70 lines
2.5 KiB
Plaintext
---
|
|
title: "Prepared statements"
|
|
sidebarTitle: "Prepared Statements"
|
|
description: "What a deployment does when a Flight SQL client prepares a statement or binds parameter values."
|
|
icon: bolt
|
|
keywords: ["prepared statement", "flight sql", "parameters", "bind"]
|
|
availability:
|
|
embedded: unavailable
|
|
enterprise: available
|
|
---
|
|
|
|
A Flight SQL client can prepare a statement before it runs it. A deployment
|
|
accepts that, but it keeps no plan between runs and does not accept parameter
|
|
values.
|
|
|
|
## Prepare through a Flight SQL client {#protocol}
|
|
|
|
<Warning>
|
|
There is no SQL `PREPARE` / `EXECUTE` here. Preparation is part of the
|
|
**Arrow Flight SQL protocol**, so you reach it through your client rather than
|
|
by sending a statement.
|
|
</Warning>
|
|
|
|
That distinction matters when porting SQL from another engine: a script
|
|
containing `PREPARE name AS SELECT ...` will not run.
|
|
|
|
## Prepare and execute {#flow}
|
|
|
|
A Flight SQL client takes these steps, whatever it calls them:
|
|
|
|
1. **Prepare:** send the SQL and get back a handle and the result schema. The
|
|
statement is parsed and planned at this point, so a syntax or name error
|
|
surfaces here rather than at execution.
|
|
2. **Execute:** run the handle and read the result. The deployment plans the
|
|
statement again each time it runs, so reusing a handle does not save
|
|
planning time.
|
|
3. **Close:** release the handle.
|
|
|
|
## Parameters {#parameters}
|
|
|
|
A deployment does not accept parameter values for a prepared statement. A
|
|
client that binds values to placeholders such as `$1` and `$2` gets a "not
|
|
implemented" error when it executes the statement. A statement with fixed,
|
|
trusted values written into it runs as usual:
|
|
|
|
```sql
|
|
SELECT id, title FROM documents WHERE category = 'news' AND score > 0.5
|
|
```
|
|
|
|
Do not put untrusted input, such as a value from a user or a request, directly
|
|
into the statement text. Quoting it does not protect the statement the way
|
|
binding a parameter would.
|
|
|
|
<Note>
|
|
This limitation is specific to the Flight SQL protocol's `PREPARE`/bind step.
|
|
The Python SDK's `execute_query(sql, parameters=...)` binds parameter values
|
|
through a separate, LanceDB-specific mechanism -- see
|
|
[Parameters in SQL queries](/basics/sql#parameters).
|
|
</Note>
|
|
|
|
## When to use prepared statements {#when}
|
|
|
|
Prepare a statement when your client requires it, or to get a statement's
|
|
result schema and catch syntax and name errors without running it. Preparing
|
|
does not make a repeated statement faster.
|
|
|
|
To give a reusable query a name, create a [view](/management/view). To store
|
|
its result for later queries, create a
|
|
[materialized view](/management/materialized-view).
|