ursa.catalog._filters

Compile a filter spec into a lancedb where= SQL clause.

M2 supports the small set of predicates ursa.query (ENG-889) needs:

  • equality on a top-level column: {"col": "value"}

  • set membership on a top-level column: {"col": ["a", "b"]}

  • half-open range on a top-level column: {"col": ("between", lo, hi)}

  • raw SQL passthrough: where="col = 'x' AND ..."

Filters that target a key inside a MetadataDict column ("metadata.session": "morning") raise NotImplementedError — metadata is JSON-blobbed in M2, so pushdown filtering is impossible without the M3 promotion to Lance MapType + hot-key columns (ENG-1066).

DataFusion (Lance’s underlying SQL engine) does not honor C-style backslash escapes in string literals. Only single quotes inside string values need escaping, and the convention is to double them (' → ''). Backslashes pass through unchanged.

Module Contents

Functions

compile_where

Translate a filter spec into a DataFusion SQL string.

_compile_one

_lit

Render a Python value as a DataFusion SQL literal.

Data

__all__

API

ursa.catalog._filters.__all__

[‘compile_where’, ‘MetadataPushdownNotImplemented’]

exception ursa.catalog._filters.MetadataPushdownNotImplemented[source]

Bases: NotImplementedError

Raised when compile_where receives a "metadata.<key>" filter. Tracked by ENG-1066 (Lance MapType + hot-key promotion).

Initialization

Initialize self. See help(type(self)) for accurate signature.

ursa.catalog._filters.compile_where(filters: str | collections.abc.Mapping[str, Any] | None) → str | None[source]

Translate a filter spec into a DataFusion SQL string.

None and the empty mapping return None so callers can pass the result straight to LanceTable.search().where(...).

ursa.catalog._filters._compile_one(col: str, value: Any) → str[source]
ursa.catalog._filters._lit(value: Any) → str[source]

Render a Python value as a DataFusion SQL literal.