🔍

Fuzzycomplete

Better SQL autocomplete for the DuckDB CLI. Replaces the built-in edit-distance autocompleter with VS Code's fuzzy-matching algorithm — substring matches, camel-case awareness, and cross-database / cross-schema table-name completion.

Browse Contents

Install

-- Install the extension
INSTALL fuzzycomplete FROM community;

-- Load it into your session
LOAD fuzzycomplete;

-- After loading, autocompletion just works in the DuckDB CLI.
INSTALL fuzzycomplete FROM community;
LOAD fuzzycomplete;

-- Tab to complete table names — fuzzy matching handles substrings,
-- camelCase, and cross-database/schema lookups out of the box.

Technical Overview

Why Use Fuzzycomplete?

Fuzzycomplete replaces DuckDB's built-in autocomplete extension with code-fuzzy-match — the same fuzzy-matching algorithm that powers Visual Studio Code. Substring matches, camelCase awareness, and cross-database/cross-schema identifier lookup, all wired into the DuckDB CLI's Tab key.

⌨️ What this extension is for

This is a quality-of-life upgrade for the duckdb CLI. Once loaded, every Tab-completion in the interactive shell is fuzzy — the same matching style developers expect from VS Code's command palette and symbol search.

  • • Smarter keyword & identifier completion: Suggests SQL keywords and identifiers (databases, schemas, tables, columns) ranked by fuzzy score instead of edit distance. Typing usrs finds users; typing gnst finds getNotificationStatus.
  • • Cross-database, cross-schema: Suggestions span every ATTACH-ed database and every schema on the search path, with the right qualifier prepended automatically — useful in multi-database sessions.
  • • Drop-in replacement: Implements the same sql_auto_complete table function as the built-in autocomplete extension, so the CLI picks it up without any configuration change.
  • • Zero SQL surface to learn: There's nothing to call from queries. Install, load, hit Tab. Inspect the ranked suggestions with sql_auto_complete only if you want to.

🧠 How the matcher works

The Rust crate code-fuzzy-match is a port of the matcher VS Code uses for its command palette and Quick Open. The order of characters in your query has to appear in the candidate, but they don't have to be contiguous — and matches near word boundaries score higher.

  • • Ordered subsequence matching: Every character of your query must appear in the candidate, in order — usr matches both users and user_settings, but not setUR.
  • • Word-boundary bonuses: Characters following a separator (_, .) or at a camelCase word start score higher — gNS cleanly hits getNotificationStatus.
  • • Sequential-run bonuses: Contiguous matches outscore scattered ones, so users beats u_e_r_s for the query usr.
  • • Tie-breakers favour shorter, lexical: On equal fuzzy score, shorter candidates rank first; ties beyond that are broken lexicographically — so the obvious answer wins.

🛡️ Scope & caveats

Honest about what this is and isn't. It's a CLI input-loop tweak — there's no value in loading it from a non-interactive client.

  • • DuckDB CLI only: Tab-completion is a feature of the DuckDB CLI's line editor. Loading this extension from the Python / Node / JDBC / ODBC / Rust / WASM clients has no effect on those clients' input — they don't have a CLI line editor to plug into.
  • • Conflicts with the built-in autocomplete: Fuzzycomplete and the built-in autocomplete both register a sql_auto_complete table function. The last one loaded wins — so load fuzzycomplete after any session start-up that auto-loads autocomplete.
  • • Suggestions reflect the live catalog: Identifiers come from whatever databases and schemas are currently visible. Newly ATTACH-ed catalogs become available immediately; nothing needs to be reindexed.
  • • Algorithm choice is a matter of taste: Edit-distance (the default) and fuzzy matching favour different mistakes. If you mostly fix typos, the default may suit you better; if you mostly type partial names, fuzzy matching usually wins.

🎯 When you'll feel the difference

Long table or column names

Substring matches reach the right identifier without typing the full prefix — ordit jumps straight to order_items even with dozens of tables in scope.

Multi-database sessions

After several ATTACH calls, completion respects the search path and qualifies suggestions correctly across every attached catalog.

Code-style identifiers

camelCase and snake_case word starts are weighted properly, so gNS lands on getNotificationStatus and o_i on order_items.

Pairing with related extensions

Fuzzycomplete uses the same matching philosophy as rapidfuzz but at the CLI input layer; for in-SQL fuzzy scoring of strings inside queries, reach for rapidfuzz instead.

Deep Dive

Technical Details

What changes the moment you load it

Two lines in the DuckDB CLI is the whole installation:

INSTALL fuzzycomplete FROM community;
LOAD fuzzycomplete;

From there on, every Tab in the shell is fuzzy-matched. Type usrs and Tab, and users is the first suggestion. Type gnst against a table called getNotificationStatus — it appears at the top, because matches at camelCase word starts get a bonus. ATTACH a second database and Tab through FROM — completions span both catalogs, properly qualified.

DuckDB CLI only

Fuzzycomplete plugs into the DuckDB CLI’s interactive line editor. It has no effect when DuckDB is embedded in another process — Python, Node.js, JDBC/ODBC, Rust, WASM, and other client libraries don’t have a CLI input loop to hook into. If you want fuzzy string scoring inside SQL queries themselves, use rapidfuzz.

How it ranks suggestions

Fuzzycomplete uses the Rust crate code-fuzzy-match — a port of the matcher Visual Studio Code uses for its command palette and Quick Open. The matching rules:

  • Ordered subsequence. Every character of your query must appear in the candidate, in order. They don’t have to be contiguous — usr matches users and user_settings but not setUR.
  • Word-boundary bonuses. Characters that follow a separator (_, .) or sit at a camelCase boundary score higher. That’s why gNS reliably picks getNotificationStatus.
  • Run bonuses. Contiguous match runs score higher than scattered hits — users beats u_e_r_s for the query usr.
  • Tie-breakers. Equal fuzzy scores break by candidate length (shorter wins), then lexicographically.

Replaces, not supplements, the built-in

DuckDB ships an autocomplete extension that uses edit-distance scoring. Both that extension and this one register a function called sql_auto_complete — and the DuckDB CLI calls whatever’s currently registered. Whichever extension was loaded last wins. If your environment auto-loads the built-in autocomplete on session start, run LOAD fuzzycomplete afterwards (or in your ~/.duckdbrc) so fuzzycomplete takes over.

Inspecting the matcher from SQL

Tab-completion in the CLI calls sql_auto_complete under the hood, but you can also query it directly — useful for sanity-checking ranking, for tests, or for scripts that want to surface suggestions:

SELECT trim(suggestion) AS suggestion
FROM sql_auto_complete('SELECT * FROM ord')
LIMIT 5;

The function returns rows ordered best-first. It walks the live catalog, so newly ATTACH-ed databases and freshly created tables show up immediately — there’s no separate index to refresh.

What’s in the box

SurfaceWhere it lives
Tab-completion in the CLIImplicit — DuckDB’s line editor calls sql_auto_complete on every Tab
sql_auto_complete(query)One table function; returns ranked suggestions for a partial SQL string
ConfigurationNone — install, load, done

For SQL-level fuzzy primitives (similarity scores, distances, record linkage) load rapidfuzz. For prefix-tree lookups against large dictionaries, load marisa.

API Reference

Function Documentation

Detailed documentation for each function including signatures, parameters, and examples.

sql_auto_complete

Scalar Function Autocomplete
Signature
sql_auto_complete(query: VARCHAR) →
Parameters (Positional)
Parameter Type Mode Description
query VARCHAR Positional The partial SQL text the user has typed. Suggestions are ranked by fuzzy match score against keywords and identifiers (databases, schemas, tables, columns) currently visible to the session.
Returns
Description

Return ranked autocomplete suggestions for a partial SQL string using the VS-Code-derived fuzzy matcher. Loaded by the DuckDB CLI to power Tab-completion; you can also call it directly in SQL to inspect what the completer would suggest. Replaces the function of the same name from the built-in autocomplete extension when this extension is loaded.

Examples
1

Complete a SQL keyword — the top suggestion for `SEL` is `SELECT`.

SELECT trim(suggestion) AS suggestion
FROM sql_auto_complete('SEL')
LIMIT 3;
2

Suggest a table name after `FROM` — the completer walks every attached database and schema in the search path.

SELECT suggestion
FROM sql_auto_complete('SELECT * FROM tables')
LIMIT 1;
3

Substring + camelCase matching — typing `gnst` finds `getNotificationStatus` even though it isn't a prefix.

SELECT suggestion
FROM sql_auto_complete('SELECT * FROM gnst');
Back to Extension Contents

Practical Examples

Cookbook

Real-world recipes and patterns for common use cases.

What this changes

fuzzycomplete replaces DuckDB’s stock autocomplete with code-fuzzy-match — the same fuzzy matcher VS Code uses. Once loaded, hitting Tab in the DuckDB CLI matches:

  • Substrings — typing usrs finds users.
  • Camel-case word starts — gnst finds getNotificationStatus.
  • Across databases & schemas — completion respects the search path even with multiple ATTACH-ed databases.

It’s a CLI-only quality-of-life win — there’s no SQL surface to call.

Setup

INSTALL fuzzycomplete FROM community;
LOAD fuzzycomplete;

After loading, completion in the CLI uses the new algorithm automatically. No configuration needed.

When you’ll notice the difference

  • Long table names — fuzzy substring matches reach the right table without typing the full prefix.
  • Multi-DB sessions — completion includes tables from every attached database, with the right qualifier.
  • Code-style identifiers — camelCase / snake_case word starts are weighted properly.

For applications, IDEs, and other clients connecting to DuckDB programmatically, this extension has no effect — it’s the CLI’s input loop only.

Back to Top

Platform Support

Compatibility

Extension availability may vary by platform and DuckDB version. Check below to ensure this extension supports your environment before installation.

Quick Facts

Software License MIT
Pricing Free
Written In Rust
Source Available Yes
View on GitHub
Usage
14,655+
loads in last 30 days

Platforms

Linux
Linux (musl)
macOS
Windows
WASM
Supported platform architectures
Linux: aarch64, x86_64
Linux (musl): Not available
macOS: Apple Silicon, Intel
Windows: x86_64
WASM: Not available
Compiled binary sizes
Platform Architecture Size
Linux aarch64 3.62 MB
Linux x86_64 4.01 MB
macOS Apple Silicon 2.00 MB
macOS Intel 2.31 MB
Windows x86_64 7.57 MB

Gzipped download size from the DuckDB community-extensions registry.

DuckDB Versions

Release calendar
Supported
v1.4.4 v1.5.2

Smarter CLI Autocomplete

Install fuzzycomplete in the DuckDB CLI for VS-Code-style fuzzy autocomplete that crosses database and schema boundaries.

Install Now View Other Extensions