Dialects

SQLSpec registers custom sqlglot dialects that extend built-in SQL grammars with extension-specific operators. These dialects enable the builder to parse and generate SQL that uses vendor-specific syntax (e.g., pgvector distance operators, ParadeDB search operators).

The dialects are registered lazily through the sqlglot.dialects entry-point group, so sqlglot.parse_one(..., dialect="pgvector") resolves them in any environment where SQLSpec is installed; importing sqlspec alone does not load them. Import the classes directly when you need them as objects:

from sqlspec.dialects import PGTextSearch, PGVector, ParadeDB, Spanner, Spangres

Performance builds compile the custom dialect helper modules alongside sqlglot[c]: generator transforms, operator registries, and compatibility helpers. The small SQLGlot subclass/registration modules stay interpreted because native-compiling those tokenizer/dialect classes is not runtime-safe.

PostgreSQL Extensions

PGVector

class sqlspec.dialects.postgres.PGVector

Bases: Postgres

PostgreSQL dialect with pgvector extension support.

Tokenizer

alias of PGVectorTokenizer

BYTE_STRINGS_SUPPORT_ESCAPED_SEQUENCES: bool = True

Whether byte string literals support escape sequences. Set by the metaclass based on the tokenizer's BYTE_STRING_ESCAPES.

IDENTIFIER_ESCAPED_SEQUENCES: dict[str, str] = {}

Mapping of an identifier escape char (`) to its escaped version (\`). Set by the metaclass based on the tokenizer's IDENTIFIER_ESCAPES.

STRINGS_SUPPORT_ESCAPED_SEQUENCES: bool = False

Whether string literals support escape sequences (e.g. n). Set by the metaclass based on the tokenizer's STRING_ESCAPES.

SUPPORTS_COLUMN_JOIN_MARKS = False

Whether the old-style outer join (+) syntax is supported.

UNESCAPED_SEQUENCES: dict[str, str] = {'\\\\': '\\', '\\a': 'a', '\\b': '\x08', '\\f': '\x0c', '\\n': '\n', '\\r': '\r', '\\t': '\t', '\\v': '\x0b'}

Mapping of an escaped sequence (n) to its unescaped version (` `).

tokenizer_class

alias of PGVectorTokenizer

Adds support for pgvector distance operators:

Operator	Description
<->	L2 (Euclidean) distance
<#>	Negative inner product
<=>	Cosine distance
<+>	L1 (Manhattan) distance
<~>	Hamming distance (binary vectors)
<%>	Jaccard distance (binary vectors)

PGTextSearch

class sqlspec.dialects.postgres.PGTextSearch

Bases: Postgres

PostgreSQL dialect with pg_textsearch and pgvector extension support.

Tokenizer

alias of PGTextSearchTokenizer

BYTE_STRINGS_SUPPORT_ESCAPED_SEQUENCES: bool = True

Whether byte string literals support escape sequences. Set by the metaclass based on the tokenizer's BYTE_STRING_ESCAPES.

IDENTIFIER_ESCAPED_SEQUENCES: dict[str, str] = {}

Mapping of an identifier escape char (`) to its escaped version (\`). Set by the metaclass based on the tokenizer's IDENTIFIER_ESCAPES.

STRINGS_SUPPORT_ESCAPED_SEQUENCES: bool = False

Whether string literals support escape sequences (e.g. n). Set by the metaclass based on the tokenizer's STRING_ESCAPES.

SUPPORTS_COLUMN_JOIN_MARKS = False

Whether the old-style outer join (+) syntax is supported.

UNESCAPED_SEQUENCES: dict[str, str] = {'\\\\': '\\', '\\a': 'a', '\\b': '\x08', '\\f': '\x0c', '\\n': '\n', '\\r': '\r', '\\t': '\t', '\\v': '\x0b'}

Mapping of an escaped sequence (n) to its unescaped version (` `).

tokenizer_class

alias of PGTextSearchTokenizer

Adds support for PostgreSQL deployments with the pg_textsearch BM25 extension installed. AlloyDB currently provides this extension in preview on PostgreSQL 17 and 18; see AlloyDB BM25 requirements. Server packaging and version support are independent of SQLSpec dialect availability.

Operator	Description
<@>	BM25 score ranking operator (returns negative score for ASC index scans)

Indexes are created with USING bm25 (column) WITH (text_config='english') and queries order by column <@> 'query' ASC. Enable the extension in the database before using its operators or index method. The dialect also supports pgvector distance operators for hybrid queries.

Asyncpg, psycopg, psqlpy, and PostgreSQL-backed ADBC configurations probe enabled extensions on first connection. enable_pg_textsearch defaults to True; setting it to False disables detection, not the installed server extension. pg_textsearch_available and is_postgres_extension_active() report the cached, enabled-and-detected state, and remain false before a successful probe. ADK enable_bm25 requires successful pg_textsearch detection.

The dialect label remains selected in priority order: paradedb, pg_textsearch, then pgvector for an otherwise default PostgreSQL configuration. The active extension set records all enabled discoveries independently. An explicitly selected non-default dialect is preserved; select a dialect that supports the operators your queries use. Extension detection does not override that choice, and a dialect label alone does not mark an extension as available.

ParadeDB

class sqlspec.dialects.postgres.ParadeDB

Bases: Postgres

ParadeDB dialect with pg_search and pgvector extension support.

Tokenizer

alias of ParadeDBTokenizer

BYTE_STRINGS_SUPPORT_ESCAPED_SEQUENCES: bool = True

Whether byte string literals support escape sequences. Set by the metaclass based on the tokenizer's BYTE_STRING_ESCAPES.

IDENTIFIER_ESCAPED_SEQUENCES: dict[str, str] = {}

Mapping of an identifier escape char (`) to its escaped version (\`). Set by the metaclass based on the tokenizer's IDENTIFIER_ESCAPES.

STRINGS_SUPPORT_ESCAPED_SEQUENCES: bool = False

Whether string literals support escape sequences (e.g. n). Set by the metaclass based on the tokenizer's STRING_ESCAPES.

SUPPORTS_COLUMN_JOIN_MARKS = False

Whether the old-style outer join (+) syntax is supported.

UNESCAPED_SEQUENCES: dict[str, str] = {'\\\\': '\\', '\\a': 'a', '\\b': '\x08', '\\f': '\x0c', '\\n': '\n', '\\r': '\r', '\\t': '\t', '\\v': '\x0b'}

Mapping of an escaped sequence (n) to its unescaped version (` `).

tokenizer_class

alias of ParadeDBTokenizer

Extends PostgreSQL with ParadeDB (pg_search) operators:

Operator	Description
@@@	BM25 full-text search / complex query expressions
&&&	Conjunction match (all tokenized terms must match)
|||	Disjunction match (any tokenized term matches)
===	Exact term match (no tokenization of right-hand side)
###	Exact phrase match (token order and position enforced)
##	Proximity match in any order ('a' ## n ## 'b')
##>	Ordered proximity match (left term must appear first)

Scoring and snippets in ParadeDB are standard SQL functions (pdb.score(), pdb.snippet()), so they require no custom operator syntax.

Spanner

class sqlspec.dialects.spanner.Spanner

Bases: BigQuery

Google Cloud Spanner SQL dialect.

Tokenizer

alias of SpannerTokenizer

parse(sql, **opts)

Parse Spanner SQL statements and attach hints.

Return type:

list[Expr | None]

parse_into(expression_type, sql, **opts)

Parse into specific expression type with attached hints.

Return type:

list[Expr | None]

BYTE_STRINGS_SUPPORT_ESCAPED_SEQUENCES: bool = True

Whether byte string literals support escape sequences. Set by the metaclass based on the tokenizer's BYTE_STRING_ESCAPES.

IDENTIFIER_ESCAPED_SEQUENCES: dict[str, str] = {}

Mapping of an identifier escape char (`) to its escaped version (\`). Set by the metaclass based on the tokenizer's IDENTIFIER_ESCAPES.

STRINGS_SUPPORT_ESCAPED_SEQUENCES: bool = True

Whether string literals support escape sequences (e.g. n). Set by the metaclass based on the tokenizer's STRING_ESCAPES.

SUPPORTS_COLUMN_JOIN_MARKS = False

Whether the old-style outer join (+) syntax is supported.

UNESCAPED_SEQUENCES: dict[str, str] = {'\\\\': '\\', '\\a': '\x07', '\\b': '\x08', '\\f': '\x0c', '\\n': '\n', '\\r': '\r', '\\t': '\t', '\\v': '\x0b'}

Mapping of an escaped sequence (n) to its unescaped version (` `).

tokenizer_class

alias of SpannerTokenizer

class sqlspec.dialects.spanner.Spangres

Bases: Postgres

Spanner PostgreSQL-compatible dialect.

parse(sql, **opts)

Parse Spangres SQL statements and attach hints.

Return type:

list[Expr | None]

parse_into(expression_type, sql, **opts)

Parse into specific expression type with attached hints.

Return type:

list[Expr | None]

BYTE_STRINGS_SUPPORT_ESCAPED_SEQUENCES: bool = True

Whether byte string literals support escape sequences. Set by the metaclass based on the tokenizer's BYTE_STRING_ESCAPES.

IDENTIFIER_ESCAPED_SEQUENCES: dict[str, str] = {}

Mapping of an identifier escape char (`) to its escaped version (\`). Set by the metaclass based on the tokenizer's IDENTIFIER_ESCAPES.

STRINGS_SUPPORT_ESCAPED_SEQUENCES: bool = False

Whether string literals support escape sequences (e.g. n). Set by the metaclass based on the tokenizer's STRING_ESCAPES.

SUPPORTS_COLUMN_JOIN_MARKS = False

Whether the old-style outer join (+) syntax is supported.

UNESCAPED_SEQUENCES: dict[str, str] = {'\\\\': '\\', '\\a': 'a', '\\b': '\x08', '\\f': '\x0c', '\\n': '\n', '\\r': '\r', '\\t': '\t', '\\v': '\x0b'}

Mapping of an escaped sequence (n) to its unescaped version (` `).

The spanner (GoogleSQL) and spangres (PostgreSQL-interface) dialects support Spanner-specific DDL and analytical SQL:

• Table Hierarchy & TTL: INTERLEAVE IN [PARENT] <parent> [ON DELETE CASCADE | NO ACTION] and bidirectional transpilation between ROW DELETION POLICY (OLDER_THAN(col, INTERVAL n DAY)) (spanner) and TTL INTERVAL 'n days' ON col (spangres).

• Property Graph: CREATE [OR REPLACE] PROPERTY GRAPH [IF NOT EXISTS] ... NODE TABLES (...) [EDGE TABLES (...)], DROP PROPERTY GRAPH [IF EXISTS], and GRAPH_TABLE(<graph> MATCH <pattern> [WHERE <expr>] COLUMNS (...)).

• Vector Search: FLOAT32 and ARRAY<FLOAT32>(vector_length => N) columns, CREATE VECTOR INDEX [IF NOT EXISTS] ... [STORING (...)] WHERE col IS NOT NULL OPTIONS (...), DROP VECTOR INDEX [IF EXISTS], and distance functions (COSINE_DISTANCE, APPROX_COSINE_DISTANCE, EUCLIDEAN_DISTANCE, DOT_PRODUCT).

• Full-Text Search: TOKENLIST generated columns (including AS (TOKENIZE_FULLTEXT(...)) HIDDEN), CREATE SEARCH INDEX, DROP SEARCH INDEX [IF EXISTS], SEARCH(), SEARCH_SUBSTRING(), SCORE(), SCORE_NGRAMS(), and SNIPPET().

• Sequences, Returning & Hints: CREATE/ALTER SEQUENCE, GET_NEXT_SEQUENCE_VALUE(SEQUENCE seq), THEN RETURN [WITH ACTION], and @{FORCE_INDEX=...} / /*@ ... */ hints.

class sqlspec.dialects.spanner.SpannerPropertyGraph

Bases: object

AST node builder and type matcher for a Cloud Spanner PROPERTY GRAPH definition.

static __new__(cls, *, this, node_tables, edge_tables=None)

Return type:

Self

class sqlspec.dialects.spanner.SpannerGraphTable

Bases: object

AST node builder and type matcher for a Cloud Spanner GRAPH_TABLE(...) query expression.

static __new__(cls, *, this, match, columns, where=None)

Return type:

Self

sqlspec.dialects.spanner.graph_table(graph, match, columns, where=None)

Build a Spanner GRAPH_TABLE(...) expression.

Return type:

SpannerGraphTable

sqlspec.dialects.spanner.approx_cosine_distance(this, expression, options=None)

Build an APPROX_COSINE_DISTANCE function call.

Return type:

Anonymous

sqlspec.dialects.spanner.cosine_distance(**args)

sqlspec.dialects.spanner.euclidean_distance(**args)

sqlspec.dialects.spanner.dot_product(**args)

sqlspec.dialects.spanner.tokenize_fulltext(this, *expressions)

Build a TOKENIZE_FULLTEXT function call.

Return type:

Anonymous

sqlspec.dialects.spanner.tokenize_substring(this)

Build a TOKENIZE_SUBSTRING function call.

Return type:

Anonymous

sqlspec.dialects.spanner.tokenize_ngrams(this)

Build a TOKENIZE_NGRAMS function call.

Return type:

Anonymous

sqlspec.dialects.spanner.search(**args)

sqlspec.dialects.spanner.search_substring(this, expression)

Build a SEARCH_SUBSTRING function call.

Return type:

Anonymous

sqlspec.dialects.spanner.score(this, expression)

Build a SCORE function call.

Return type:

Anonymous

sqlspec.dialects.spanner.score_ngrams(this, expression, *expressions)

Build a SCORE_NGRAMS function call.

Return type:

Anonymous

sqlspec.dialects.spanner.snippet(this, expression, *expressions)

Build a SNIPPET function call.

Return type:

Anonymous

sqlspec.dialects.spanner.get_next_sequence_value(this)

Build a GET_NEXT_SEQUENCE_VALUE function call.

Return type:

Anonymous

Expression Types

sqlspec.builder.VectorDistance(*, this, expression, metric='euclidean')

Build a SQLSpec vector-distance expression.

Return type:

Operator