---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: cardinal
excerpt: |
  DuckDB Community Extensions
  Better cardinality estimates for DuckDB's join-order optimizer, learned from your tables with Bayesian networks

extension:
  name: cardinal
  description: Better cardinality estimates for DuckDB's join-order optimizer, learned from your tables with Bayesian networks
  version: 0.1.0
  language: C++
  build: cmake
  license: MIT
  excluded_platforms: "wasm_mvp;wasm_eh;wasm_threads"
  maintainers:
    - MaxHalford

repo:
  github: MaxHalford/cardinal
  ref: 4fcae2efa9ba7e1b2ed198af92e91599238e777b

docs:
  hello_world: |
    -- Moderators, 1% of users, make half of the edits.
    CREATE TABLE users AS SELECT range AS id, range % 100 = 0 AS moderator FROM range(10000);
    CREATE TABLE edits AS
    SELECT CASE WHEN range % 2 = 0 THEN (range // 2) % 100 * 100 ELSE range % 10000 END AS user_id
    FROM range(100000);

    -- The join's estimate is ~59,000 rows with cardinal, ~20,000 without. The true count is 50,000.
    EXPLAIN SELECT count(*) FROM users u, edits e WHERE u.id = e.user_id AND u.moderator;

    -- Plan without cardinal, for this connection.
    SET cardinal_estimator = 'off';
  extended_description: |
    DuckDB picks a join order from estimates of how many rows each join produces. Those estimates
    assume columns are independent, so on real data they can be off by orders of magnitude.

    cardinal learns a Bayesian network per table, the first time a query needs it, and gives DuckDB
    its estimates instead. There is nothing to configure. Results never change, only plans. On the
    STATS-CEB benchmark, total runtime goes from 130 s to 67 s.

    Models are saved in `~/.duckdb/extension_data/cardinal/`, never in your database. Only DuckDB
    tables are estimated: queries on Parquet or CSV files are planned by DuckDB alone.

    Documentation, benchmarks and limits: https://github.com/MaxHalford/cardinal

extension_star_count: 1
extension_star_count_pretty: 1
extension_download_count: null
extension_download_count_pretty: n/a
image: '/images/community_extensions/social_preview/preview_community_extension_cardinal.png'
layout: community_extension_doc
---
### Compatibility Matrix

This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

<div class="extension_compatibility_table"></div>

| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ❌ | ❌ | ❌ | ❌ | ✅ |
| Linux ARM64 | ❌ | ❌ | ❌ | ❌ | ✅ |
| macOS AMD64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| macOS ARM64 | ❌ | ❌ | ❌ | ❌ | ✅ |
| Windows AMD64 | ❌ | ❌ | ❌ | ❌ | ✅ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ❌ | ❌ | ❌ | ❌ | ❌ |

### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```

{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}

{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions

<div class="extension_functions_table"></div>

|   function_name    | function_type | description | comment | examples |
|--------------------|---------------|-------------|---------|----------|
| cardinal_fit_eager | table         | NULL        | NULL    |          |
| cardinal_models    | table         | NULL        | NULL    |          |

### Overloaded Functions

<div class="extension_functions_table"></div>

This extension does not add any function overloads.

### Added Types

<div class="extension_types_table"></div>

This extension does not add any types.

### Added Settings

<div class="extension_settings_table"></div>

|        name         |                                      description                                       | input_type | scope  | aliases | typed_value |
|---------------------|----------------------------------------------------------------------------------------|------------|--------|---------|-------------|
| cardinal_background | Fit models on a worker thread: queries plan with what there is meanwhile               | BOOLEAN    | GLOBAL | []      | false       |
| cardinal_estimator  | Cardinal's estimates for the optimizer: on or off                                      | VARCHAR    | GLOBAL | []      | on          |
| cardinal_save       | Save fitted models in the store                                                        | BOOLEAN    | GLOBAL | []      | true        |
| cardinal_store      | The models' file. Empty: ~/.duckdb/extension_data/cardinal/<DuckDB version>/store-2.db | VARCHAR    | GLOBAL | []      |             |
| temp_directory      | Set the directory to which temporary files are written.                                | VARCHAR    | GLOBAL | []      | post.db.tmp |