> ## Documentation Index
> Fetch the complete documentation index at: https://better-duck.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# DuckDB Essentials

> An orientation to DuckDB through the better-duck driver — the dialect, the type system, extensions, and engine behaviors — with pointers to the focused deep-dive pages.

DuckDB is an in-process OLAP SQL engine. better-duck embeds it (compiled straight into your binary —
see [Architecture](/guide/architecture)) and talks to its C API. This page is a short orientation to
the engine behaviors that matter when you drive DuckDB from Rust, with links to the focused pages
that cover each in depth.

<CardGroup cols={2}>
  <Card title="SQL dialect & statements" icon="code" href="/guide/sql-dialect">
    The PostgreSQL-like dialect and analytics extras, batch vs single statements, parameters, and
    transactions.
  </Card>

  <Card title="Type system" icon="table-cells" href="/guide/type-system">
    Every DuckDB type as a `DuckValue`, NULL and validity, the lossless `TypeInfo`, and
    feature-dependent read types.
  </Card>

  <Card title="Extensions" icon="puzzle-piece" href="/guide/extensions">
    Bundled at build time (`json` / `parquet` / `icu`) vs loaded at runtime (`spatial` and more).
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/guide/error-handling">
    How failures surface, DuckDB's typed `EngineError`, and the `panic = "abort"` caveat.
  </Card>
</CardGroup>

## The one-page tour

* **Dialect.** DuckDB's SQL is PostgreSQL-like with analytics extras — `QUALIFY`, `GROUP BY ALL`,
  `SELECT * EXCLUDE (...)`, `COLUMNS(...)`, list/struct/map literals, `UNNEST`, `PIVOT`, and friendly
  casting (`x::t`, `TRY_CAST`). Full tour on [SQL dialect](/guide/sql-dialect).
* **Statements.** [`execute_batch`](/guide/sql-dialect#batch-vs-single-statements) runs many
  `;`-separated statements (DuckDB does the parsing); a single `execute` prepares and runs one.
  `SELECT` / `RETURNING` yield rows, DML reports a `changes()` count, DDL changes nothing.
* **Parameters.** Positional (`$1`, `?`) via `execute_with`, named (`$name`) via
  `execute_with_named`. See [parameters](/guide/sql-dialect#parameters-positional-and-named).
* **Types.** Values arrive as [`DuckValue`](/guide/type-system), covering every integer width,
  `DECIMAL`, `UUID`, `BIT`, `BIGNUM`, temporals, and the composite `LIST` / `ARRAY` / `STRUCT` /
  `MAP` / `UNION` / `ENUM`. The read type for temporals/decimals/UUID depends on
  [feature flags](/guide/feature-flags).
* **NULL.** First-class — `DuckValue::Null`, a per-column validity bitmask in
  [columnar access](/core/columnar-overview), and `Option<T>` round-tripping.
* **Extensions.** Either [bundled at build time](/guide/extensions#bundled-at-build-time)
  (no runtime install) or [loaded at runtime](/guide/extensions#loaded-at-runtime) via the extension
  API.
* **Transactions.** Driven as SQL (`BEGIN` / `COMMIT` / `ROLLBACK`) — **no savepoints**. See
  [transactions](/core/transactions).

## Two engine behaviors worth memorizing

<Warning>
  **Row mode vs chunk mode — do not mix.** A [`DuckResult`](/core/iterating-results) is consumed
  **either** row-by-row (`next` / `exists` / `count` / `materialize`) **or** chunk-by-chunk
  (`fetch_chunk`, feature [`columnar`](/guide/feature-flags)) — never both. Mixing them yields
  `Error::MixedIterationMode`. See [columnar access](/core/columnar-overview).
</Warning>

<Warning>
  **A failed appender flush is unrecoverable.** DuckDB invalidates the [`Appender`](/core/appender)
  on a failed flush and the buffered data is lost; the appender poisons and refuses further calls. See
  [error handling](/guide/error-handling#appender-poisoning).
</Warning>

## DuckDB version

better-duck pins a specific vendored DuckDB in `better-duck-sys`;
[`better_duck_core::library_version()`](/core/opening-connections#library-version) returns the linked version
string at runtime (e.g. `"v1.5.5"`). See
[Versioning & compatibility](/guide/versioning-and-compatibility).

## Related

<CardGroup cols={2}>
  <Card title="Queries, Results & Values" icon="table" href="/core/iterating-results">
    The `DuckValue` type, parameter binding, and result metadata in depth.
  </Card>

  <Card title="Appender" icon="bolt" href="/core/appender">
    Bulk ingest and the data-chunk path.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.