---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: tessera
excerpt: |
  DuckDB Community Extensions
  Fast join-aggregates (pair counts and sums of self-joins and two-relation joins) over skewed sparse relations, with a sparse product and a CPU matrix accelerator

extension:
  name: tessera
  description: Fast join-aggregates (pair counts and sums of self-joins and two-relation joins) over skewed sparse relations, with a sparse product and a CPU matrix accelerator
  version: 1.2.1
  language: C++
  build: cmake
  license: Apache-2.0
  excluded_platforms: "linux_arm64;linux_amd64_musl;linux_arm64_musl;osx_amd64;windows_amd64;windows_arm64;windows_amd64_mingw;wasm_mvp;wasm_eh;wasm_threads"
  requires_toolchains: "omp"
  maintainers:
    - GyuyeongKim

repo:
  github: GyuyeongKim/Tessera-public
  ref: dd3efd594a5954dd3abc6661cd7892b77c81924e

docs:
  hello_world: |
    CREATE TABLE r AS
      SELECT (random() * 20000)::INTEGER AS k, floor(power(random(), 3) * 5000)::INTEGER AS x FROM range(2000000);
    -- the five pairs of values that share the most keys; Tessera replaces the join and the aggregation
    SELECT a.x AS x0, b.x AS x1, COUNT(*) AS c
    FROM r a JOIN r b ON a.k = b.k AND a.x < b.x
    GROUP BY a.x, b.x ORDER BY c DESC LIMIT 5;
    EXPLAIN SELECT a.x, b.x, COUNT(*) FROM r a JOIN r b ON a.k = b.k GROUP BY a.x, b.x;
    -- item similarity above a threshold
    SELECT * FROM tessera_sim('r', 'k', 'x', 'jaccard', 0.2);
  extended_description: |
    Tessera is an optimizer rule and operator for join-aggregates, queries that count or sum the joined rows of each
    pair of values: `SELECT a.x, b.x, COUNT(*) FROM R a JOIN R b ON a.k = b.k GROUP BY a.x, b.x`, also with
    `SUM(a.v * b.v)`, `a.x < b.x`, `HAVING`, `ORDER BY ... LIMIT`, or a second relation. It never builds the joined
    rows. It computes each pair once on a sparse path, drops the values that cannot reach a `HAVING` or top-k threshold
    before any product, and runs the dense block of the most frequent values on Intel AMX where the CPU has it. The rule
    replaces matching plans by itself, so the SQL stays unchanged. Settings: `tessera_enabled`, `tessera_frontier`,
    `tessera_min_expansion`, `tessera_min_expansion_cross`. See https://github.com/GyuyeongKim/Tessera-public for the
    supported queries, the PostgreSQL, SQLite, and Spark adapters, and the C interface.

extension_star_count: 6
extension_star_count_pretty: 6
extension_download_count: null
extension_download_count_pretty: n/a
image: '/images/community_extensions/social_preview/preview_community_extension_tessera.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 |
|---------------|---------------|-------------|---------|----------|
| tessera_sim   | 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 |
|-----------------------------|-------------------------------------------------------------------------------------------------------|------------|--------|---------|-------------|
| temp_directory              | Set the directory to which temporary files are written.                                               | VARCHAR    | GLOBAL | []      | post.db.tmp |
| tessera_enabled             | Replace self-join aggregates by the Tessera operator                                                  | BOOLEAN    | GLOBAL | []      | true        |
| tessera_frontier            | Tessera dense frontier: items < H on the matrix engine (-1: cost model)                               | BIGINT     | GLOBAL | []      | -1          |
| tessera_min_expansion       | Tessera: the engine's plan keeps self-joins with fewer estimated joined rows per input row (0: never) | DOUBLE     | GLOBAL | []      | 6.0         |
| tessera_min_expansion_cross | Tessera: the same limit for products of two relations (0: never)                                      | DOUBLE     | GLOBAL | []      | 6.0         |
| tessera_reorder             | Tessera: shingle order of the rows for the dense grid                                                 | BOOLEAN    | GLOBAL | []      | true        |