Limits and compatibility
Client interfaces, the SQL dialect, bounded operations and catalog-dependent SQL.
Compatibility boundary
VegaDB SQL follows DuckDB's SQL dialect and behavior: its syntax, types, functions, casts and NULL handling. Clients reach it through three interfaces: Arrow Flight SQL, Spark Connect and the HTTP SQL API (Connect to VegaDB).
| Area | Behavior |
|---|---|
| Arrow Flight SQL | Statements, prepared statements with Arrow parameter binding, updates, bulk ingest, transactions, catalog metadata, polling and cancellation. ADBC, the Arrow Flight SQL JDBC driver and ODBC connect through it. |
| Spark Connect | PySpark and other Spark Connect clients; DataFrame operations follow Spark semantics and spark.sql runs VegaDB SQL. |
| HTTP SQL API | Streamed and asynchronous statements, sessions, retry-safe writes and stable error codes. |
| Parameters | Positional ? or numbered $n parameters, bound as typed Arrow values. |
| Transactions | Multi-statement BEGIN/COMMIT/ROLLBACK in a session, at snapshot isolation, within one catalog. |
| SQL dialect | VegaDB analytical SQL documented in this section. |
| Extensions | Not loaded through SQL. Use the built-in VegaDB functions and managed integrations. |
| System catalogs | Use information_schema and the documented metadata statements. |
Clients connect through Arrow Flight SQL (ADBC, or the Flight SQL JDBC driver for tools such as DBeaver), Spark Connect, or the HTTP SQL API.
Bounded operations
Limits protect shared service stability and vary by warehouse profile and account policy. The warehouse details and query error return the effective value when a limit is configurable.
| Resource | What to expect |
|---|---|
| Query text and expression depth | Very large generated statements can be rejected during parsing or binding. |
| Output rows and bytes | Interactive and API clients can have result limits independent of SQL LIMIT. |
| Runtime and queue time | Statements can expire while queued or executing. |
| Memory | Joins, sorts, windows, distinct aggregates and nested values are governed by warehouse memory and spill policy. |
| Recursive CTEs | Recursion and retained working state are bounded. |
Dynamic PIVOT | Number of generated columns and discovery work are bounded. |
| Aggregate state | Top-N, exact distinct, lists, histograms and quantiles have state limits. |
| Nested width/depth | Container depth, array dimensions, field count and encoded value size are bounded. |
| Federation | Catalog calls, object listings, file reads, snapshots and remote retries use service limits and timeouts. |
Do not treat a successful small query as evidence that an unbounded production form is safe. Review EXPLAIN, filter early, select only required columns and avoid collecting arbitrarily large lists or JSON values.
Catalog-dependent SQL
The following capabilities depend on the attached catalog and table registration:
- creating or altering schemas and tables;
INSERT,UPDATE,DELETEandMERGE;- schema evolution and constraint publication;
- time-travel selectors and retention;
- materialized-view destination and refresh behavior.
Managed catalogs are writable; external DuckLake, Iceberg and Delta catalogs are read-only. A transaction writes to one catalog. An unsupported write fails before data is modified. VegaDB does not silently copy an external table into managed storage to make a statement succeed.
Determinism and ordering
SQL tables are unordered. Add ORDER BY whenever result order is contractual. Functions such as first, last, list, string_agg, top-N selection and window navigation need an explicit ordering for repeatable tie behavior.
Floating-point aggregation can vary in the least significant digits when parallel reduction order changes. Use exact decimals for contractual financial results.
Unsupported behavior
Unavailable syntax or an unsupported overload returns an error. It is never delegated to an arbitrary local runtime or accepted with a different meaning. Use the stable error code, the message and the relevant reference page to decide whether to change the query, type, catalog or warehouse configuration.
Version awareness
version() identifies the connected warehouse release. information_schema.routines exposes its function overloads. Production clients should test required language features during deployment and avoid assuming that another workspace or region has already received the same release.