vecshift 0.1.0__py3-none-any.whl

vecshift/connectors/pgvector/inspect.py

@@ -0,0 +1,427 @@
+"""Read-only inspection of a pgvector column for ``vecshift doctor``.
+
+Only aggregates leave the database: per-row dimensions, norms, and hashes are computed
+in SQL, so inspecting a table never downloads its vectors.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from typing import Any
+
+import psycopg
+from psycopg import sql
+
+from vecshift.doctor.profile import AnnIndex, IndexProfile, Sample
+
+VECTOR_TYPES = ("vector", "halfvec")
+
+# pgvector's HNSW and IVFFlat limits per type.
+MAX_INDEXABLE_DIMENSIONS = {"vector": 2000, "halfvec": 4000}
+
+# Schemas that never hold user vector tables, including Supabase's internal ones.
+SYSTEM_SCHEMAS = (
+    "pg_catalog",
+    "information_schema",
+    "pg_toast",
+    "auth",
+    "storage",
+    "realtime",
+    "_realtime",
+    "supabase_functions",
+    "supabase_migrations",
+    "extensions",
+    "graphql",
+    "graphql_public",
+    "pgsodium",
+    "pgsodium_masks",
+    "vault",
+    "net",
+    "cron",
+    "pgbouncer",
+)
+
+# Common names, most likely first. Covers Supabase and LangChain (content, document),
+# LlamaIndex (text), and others.
+TEXT_COLUMNS = ("content", "text", "page_content", "document", "chunk", "chunk_text", "body")
+MODEL_COLUMNS = ("model_tag", "embedding_model", "model", "model_name")
+MODEL_METADATA_KEYS = ("model_tag", "embedding_model", "model", "model_name")
+METADATA_COLUMNS = ("metadata", "cmetadata", "meta", "metadata_")
+UPDATED_AT_COLUMNS = (
+    "updated_at",
+    "modified_at",
+    "last_modified",
+    "last_modified_at",
+    "changed_at",
+    "updated",
+    "modified",
+)
+
+TEXT_TYPES = ("text", "varchar", "bpchar")
+JSON_TYPES = ("jsonb", "json")
+TIMESTAMP_TYPES = ("timestamptz", "timestamp")
+
+_METRICS = (
+    ("cosine", "cosine"),
+    ("_ip_", "inner_product"),
+    ("l2", "l2"),
+    ("l1", "l1"),
+    ("hamming", "hamming"),
+    ("jaccard", "jaccard"),
+)
+
+
+class TargetSelectionError(Exception):
+    """The vector column to inspect couldn't be determined."""
+
+    def __init__(self, message: str, candidates: list[VectorColumn] | None = None) -> None:
+        super().__init__(message)
+        self.candidates = candidates or []
+
+
+@dataclass(frozen=True, slots=True)
+class VectorColumn:
+    schema: str
+    table: str
+    column: str
+    type: str
+    dimensions: int | None
+    relid: int
+    attnum: int
+
+    @property
+    def qualified(self) -> str:
+        return f"{self.schema}.{self.table}.{self.column}"
+
+
+def find_vector_columns(conn: psycopg.Connection) -> list[VectorColumn]:
+    """Every vector or halfvec column in a user table, view, or materialized view."""
+    rows = conn.execute(
+        """
+        SELECT n.nspname, c.relname, a.attname, t.typname, a.atttypmod, c.oid, a.attnum
+        FROM pg_attribute a
+        JOIN pg_class c ON c.oid = a.attrelid
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        JOIN pg_type t ON t.oid = a.atttypid
+        WHERE t.typname = ANY(%s)
+          AND c.relkind IN ('r', 'p', 'm')
+          AND NOT c.relispartition
+          AND a.attnum > 0
+          AND NOT a.attisdropped
+          AND n.nspname <> ALL(%s)
+          AND n.nspname NOT LIKE 'pg\\_temp\\_%%'
+        ORDER BY n.nspname, c.relname, a.attnum
+        """,
+        (list(VECTOR_TYPES), list(SYSTEM_SCHEMAS)),
+    ).fetchall()
+    return [
+        VectorColumn(
+            schema=r[0],
+            table=r[1],
+            column=r[2],
+            type=r[3],
+            dimensions=r[4] if r[4] > 0 else None,
+            relid=r[5],
+            attnum=r[6],
+        )
+        for r in rows
+    ]
+
+
+def select_column(
+    columns: list[VectorColumn], table: str | None, column: str | None
+) -> VectorColumn:
+    """Pick the column to inspect from ``--table`` and ``--column``, if given."""
+    matches = columns
+    if table:
+        schema, _, name = table.rpartition(".")
+        matches = [c for c in matches if c.table == name and (not schema or c.schema == schema)]
+        if not matches:
+            raise TargetSelectionError(
+                f"No vector columns found in table {table!r}.", candidates=columns
+            )
+    if column:
+        matches = [c for c in matches if c.column == column]
+        if not matches:
+            raise TargetSelectionError(f"No vector column named {column!r}.", candidates=columns)
+
+    if not matches:
+        raise TargetSelectionError(
+            "No pgvector columns found. Is the vector extension installed, and can this "
+            "role see the tables?"
+        )
+    if len(matches) > 1:
+        raise TargetSelectionError(
+            "Found more than one vector column. Choose one with --table (and --column).",
+            candidates=matches,
+        )
+    return matches[0]
+
+
+def _extension_schema(conn: psycopg.Connection) -> str:
+    # Supabase installs pgvector in "extensions", which isn't always on the search path,
+    # so every pgvector function call is schema-qualified.
+    row = conn.execute(
+        "SELECT n.nspname FROM pg_extension e "
+        "JOIN pg_namespace n ON n.oid = e.extnamespace WHERE e.extname = 'vector'"
+    ).fetchone()
+    if row is None:
+        raise TargetSelectionError("The pgvector extension isn't installed in this database.")
+    return str(row[0])
+
+
+def _columns(conn: psycopg.Connection, relid: int) -> dict[str, str]:
+    rows = conn.execute(
+        """
+        SELECT a.attname, t.typname
+        FROM pg_attribute a JOIN pg_type t ON t.oid = a.atttypid
+        WHERE a.attrelid = %s AND a.attnum > 0 AND NOT a.attisdropped
+        ORDER BY a.attnum
+        """,
+        (relid,),
+    ).fetchall()
+    return {r[0]: r[1] for r in rows}
+
+
+def _pick(columns: dict[str, str], names: tuple[str, ...], types: tuple[str, ...]) -> str | None:
+    lowered = {name.lower(): name for name in columns}
+    for candidate in names:
+        actual = lowered.get(candidate)
+        if actual is not None and columns[actual] in types:
+            return actual
+    return None
+
+
+def _ann_indexes(conn: psycopg.Connection, col: VectorColumn) -> list[AnnIndex]:
+    rows = conn.execute(
+        """
+        SELECT ic.relname, am.amname, opc.opcname
+        FROM pg_index i
+        JOIN pg_class ic ON ic.oid = i.indexrelid
+        JOIN pg_am am ON am.oid = ic.relam
+        CROSS JOIN LATERAL unnest(i.indkey::int2[], i.indclass::oid[]) AS k(attnum, opclass)
+        JOIN pg_opclass opc ON opc.oid = k.opclass
+        WHERE i.indrelid = %s
+          AND am.amname IN ('hnsw', 'ivfflat')
+          AND (
+            k.attnum = %s
+            -- Expression indexes, such as an HNSW index over embedding::halfvec(3072).
+            OR (k.attnum = 0 AND pg_get_indexdef(i.indexrelid) LIKE '%%' || quote_ident(%s) || '%%')
+          )
+        ORDER BY ic.relname
+        """,
+        (col.relid, col.attnum, col.column),
+    ).fetchall()
+    indexes = []
+    for name, method, opclass in rows:
+        metric = next((m for key, m in _METRICS if key in opclass), None)
+        indexes.append(AnnIndex(name=name, method=method, metric=metric))
+    return indexes
+
+
+def _rows_hidden(conn: psycopg.Connection, relid: int) -> bool:
+    row = conn.execute(
+        """
+        SELECT c.relrowsecurity, c.relforcerowsecurity,
+               pg_has_role(current_user, c.relowner, 'USAGE'),
+               r.rolbypassrls OR r.rolsuper
+        FROM pg_class c, pg_roles r
+        WHERE c.oid = %s AND r.rolname = current_user
+        """,
+        (relid,),
+    ).fetchone()
+    if row is None:
+        return False
+    enabled, forced, owner, bypass = row
+    if not enabled or bypass or (owner and not forced):
+        return False
+    # A permissive "using (true)" read policy for this role shows every row, unless a
+    # restrictive policy narrows it again.
+    sees_all = conn.execute(
+        """
+        WITH applicable AS (
+            SELECT p.polpermissive, pg_get_expr(p.polqual, p.polrelid) AS qual
+            FROM pg_policy p
+            WHERE p.polrelid = %s
+              AND p.polcmd IN ('r', '*')
+              AND (
+                0 = ANY(p.polroles)
+                OR EXISTS (
+                    SELECT 1 FROM unnest(p.polroles) AS r(oid)
+                    WHERE pg_has_role(current_user, r.oid, 'MEMBER')
+                )
+              )
+        )
+        SELECT EXISTS (SELECT 1 FROM applicable WHERE polpermissive AND qual = 'true')
+           AND NOT EXISTS (SELECT 1 FROM applicable WHERE NOT polpermissive)
+        """,
+        (relid,),
+    ).fetchone()
+    return not (sees_all and sees_all[0])
+
+
+def _sample(
+    conn: psycopg.Connection,
+    col: VectorColumn,
+    ext: str,
+    estimated_rows: int | None,
+    size: int,
+    text_field: str | None,
+    model_expr: sql.Composable,
+) -> Sample:
+    vec = sql.Identifier(col.column)
+    fn = sql.Identifier(ext, "vector_dims")
+    norm = sql.Identifier(ext, "vector_norm" if col.type == "vector" else "l2_norm")
+    has_text: sql.Composable
+    text_hash: sql.Composable
+    if text_field:
+        text = sql.Identifier(text_field)
+        has_text = sql.SQL("({t} IS NOT NULL AND btrim({t}::text) <> '')").format(t=text)
+        text_hash = sql.SQL("md5({t}::text)").format(t=text)
+    else:
+        has_text = sql.SQL("NULL::boolean")
+        text_hash = sql.SQL("NULL::text")
+
+    def query(tablesample: sql.Composable, spread: bool) -> list[tuple[Any, ...]]:
+        # Rows come back in physical order, so a bare LIMIT keeps only the start of the
+        # table. Ordering by a hash of each row's location keeps a spread-out subset
+        # instead, and the same one on every run.
+        order = sql.SQL("ORDER BY md5(ctid::text)") if spread else sql.SQL("")
+        q = sql.SQL(
+            "SELECT {vec} IS NULL, {fn}({vec}), {norm}({vec}), md5({vec}::text), "
+            "{has_text}, {text_hash}, {model} "
+            "FROM {table} {tablesample} {order} LIMIT {limit}"
+        ).format(
+            vec=vec,
+            fn=fn,
+            norm=norm,
+            has_text=has_text,
+            text_hash=text_hash,
+            model=model_expr,
+            table=sql.Identifier(col.schema, col.table),
+            tablesample=tablesample,
+            order=order,
+            limit=sql.Literal(size),
+        )
+        return conn.execute(q).fetchall()
+
+    rows: list[tuple[Any, ...]] = []
+    method = "table sample"
+    if estimated_rows and estimated_rows > size * 2:
+        # Big table: read a random ~1.5x share of its pages. SYSTEM sampling skips the
+        # other pages entirely, so this stays cheap however large the table is.
+        percent = min(100.0, 100.0 * size * 1.5 / estimated_rows)
+        tablesample = sql.SQL("TABLESAMPLE SYSTEM ({}) REPEATABLE (7)").format(sql.Literal(percent))
+        rows = query(tablesample, spread=True)
+        if len(rows) < size // 2:  # statistics overstate the size; read it whole below
+            rows = []
+    if not rows:
+        # Statistics say the table is small, so read it all and keep a spread-out subset.
+        # Without statistics it could be huge, so read only the first rows.
+        known = estimated_rows is not None
+        rows = query(sql.SQL(""), spread=known)
+        if len(rows) < size:
+            method = "full table"
+        else:
+            method = "spread across the table" if known else "first rows"
+
+    sample = Sample(rows=len(rows), method=method)
+    sample.texts_present = 0 if text_field else None
+    vector_hashes: Counter[str] = Counter()
+    text_hashes: Counter[str] = Counter()
+    model_sources: Counter[str] = Counter()
+    for is_null, dims, norm_value, vhash, text_ok, thash, model in rows:
+        if is_null:
+            sample.null_vectors += 1
+        else:
+            sample.dimensions[int(dims)] += 1
+            sample.norms.append(float(norm_value))
+            vector_hashes[vhash] += 1
+        if text_ok:
+            sample.texts_present = (sample.texts_present or 0) + 1
+            text_hashes[thash] += 1
+        if model is not None and not is_null:
+            source, _, value = str(model).partition("\t")
+            sample.models[value] += 1
+            model_sources[source] += 1
+    sample.duplicate_vectors = sum(n - 1 for n in vector_hashes.values())
+    sample.duplicate_texts = sum(n - 1 for n in text_hashes.values())
+    sample.model_source = model_sources.most_common(1)[0][0] if model_sources else None
+    return sample
+
+
+def _model_source(columns: dict[str, str]) -> tuple[str | None, sql.Composable]:
+    """Where each row records its model, as a label and an expression yielding
+    ``label<TAB>model`` (so rows can say which metadata key they used)."""
+    column = _pick(columns, MODEL_COLUMNS, TEXT_TYPES)
+    if column:
+        return column, sql.SQL("{} || E'\\t' || {}::text").format(
+            sql.Literal(column), sql.Identifier(column)
+        )
+    metadata = _pick(columns, METADATA_COLUMNS, JSON_TYPES)
+    if metadata:
+        meta = sql.Identifier(metadata)
+        keys = sql.SQL(", ").join(
+            sql.SQL("{} || E'\\t' || ({} ->> {})").format(
+                sql.Literal(f"{metadata}->>'{k}'"), meta, sql.Literal(k)
+            )
+            for k in MODEL_METADATA_KEYS
+        )
+        return metadata, sql.SQL("COALESCE({})").format(keys)
+    return None, sql.SQL("NULL::text")
+
+
+def inspect(
+    conn: psycopg.Connection,
+    table: str | None = None,
+    column: str | None = None,
+    text_column: str | None = None,
+    sample_size: int = 2000,
+) -> IndexProfile:
+    """Profile one vector column. Read-only; run it on a read-only connection."""
+    ext = _extension_schema(conn)
+    col = select_column(find_vector_columns(conn), table, column)
+    columns = _columns(conn, col.relid)
+
+    if text_column is not None:
+        if text_column not in columns:
+            raise TargetSelectionError(
+                f"Column {text_column!r} doesn't exist in {col.schema}.{col.table}."
+            )
+        text_field: str | None = text_column
+    else:
+        text_field = _pick(columns, TEXT_COLUMNS, TEXT_TYPES)
+    model_field, model_expr = _model_source(columns)
+
+    reltuples = conn.execute(
+        "SELECT reltuples::bigint FROM pg_class WHERE oid = %s", (col.relid,)
+    ).fetchone()
+    estimated = int(reltuples[0]) if reltuples and reltuples[0] >= 0 else None
+
+    sample = _sample(conn, col, ext, estimated, sample_size, text_field, model_expr)
+    if sample.method == "full table":
+        estimated = sample.rows
+
+    pk = conn.execute(
+        "SELECT EXISTS (SELECT 1 FROM pg_index WHERE indrelid = %s AND indisprimary)",
+        (col.relid,),
+    ).fetchone()
+    wal = conn.execute("SELECT current_setting('wal_level')").fetchone()
+
+    return IndexProfile(
+        store="pgvector",
+        target=col.qualified,
+        vector_type=col.type,
+        declared_dimensions=col.dimensions,
+        estimated_rows=estimated,
+        sample=sample,
+        text_field=text_field,
+        model_field=sample.model_source or model_field,
+        updated_at_field=_pick(columns, UPDATED_AT_COLUMNS, TIMESTAMP_TYPES),
+        has_primary_key=bool(pk and pk[0]),
+        logical_replication=bool(wal and wal[0] == "logical"),
+        ann_indexes=_ann_indexes(conn, col),
+        max_indexable_dimensions=MAX_INDEXABLE_DIMENSIONS.get(col.type),
+        rows_hidden_by_access_rules=_rows_hidden(conn, col.relid),
+    )

vecshift/connectors/pgvector/search.py

@@ -0,0 +1,240 @@
+"""Read-only vector searches over a migration's old and new columns, for ``vecshift eval``.
+
+Each search runs in its own read-only transaction with a statement timeout, and settings
+such as ``hnsw.ef_search`` are set for that transaction only.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Literal
+
+import psycopg
+from psycopg import sql
+
+from vecshift.connectors.pgvector.target import OPCLASS_SUFFIX
+
+Side = Literal["old", "new"]
+
+OPERATORS = {"cosine": "<=>", "l2": "<->", "inner_product": "<#>"}
+SETTINGS = {"hnsw": "hnsw.ef_search", "ivfflat": "ivfflat.probes"}
+DEFAULTS = {"hnsw": 40, "ivfflat": 1}
+SWEEP = {"hnsw": (40, 100, 200), "ivfflat": (1, 5, 10, 20)}
+TIMEOUT_MS = 60_000
+
+
+class PgSearcher:
+    def __init__(
+        self,
+        conn: psycopg.Connection,
+        *,
+        schema: str,
+        table: str,
+        pk: str,
+        columns: Mapping[Side, str],
+        types: Mapping[Side, str],
+        extension_schema: str,
+        metric: str,
+        partial: bool = False,
+        group: sql.Composable | None = None,
+        timeout_ms: int = TIMEOUT_MS,
+    ) -> None:
+        if metric not in OPERATORS:
+            raise ValueError(f"unsupported metric {metric!r}")
+        if not set(types.values()) <= {"vector", "halfvec"}:
+            raise ValueError("unsupported vector type")
+        self.conn = conn
+        self.table = sql.Identifier(schema, table)
+        self.pk = sql.Identifier(pk)
+        self.columns = {side: sql.Identifier(name) for side, name in columns.items()}
+        self.names = dict(columns)
+        self.types = {side: sql.Identifier(extension_schema, kind) for side, kind in types.items()}
+        self.operator = sql.SQL("OPERATOR({}.{})").format(
+            sql.Identifier(extension_schema), sql.SQL(OPERATORS[metric])
+        )
+        self.metric = metric
+        self.partial = partial
+        self.group = group if group is not None else sql.SQL("NULL")
+        self.timeout_ms = int(timeout_ms)
+        self._indexes: dict[Side, tuple[str | None, int | None, list[int]]] = {}
+
+    # --- plumbing
+
+    def _run(
+        self, query: sql.SQL | sql.Composed, params: Sequence[Any], settings: Mapping[str, str]
+    ) -> list[tuple[Any, ...]]:
+        try:
+            self.conn.execute(
+                "SELECT set_config('statement_timeout', %s, true)", (str(self.timeout_ms),)
+            )
+            for name, value in settings.items():
+                self.conn.execute("SELECT set_config(%s, %s, true)", (name, value))
+            return self.conn.execute(query, params).fetchall()
+        finally:
+            self.conn.rollback()
+
+    @staticmethod
+    def _literal(vector: Sequence[float]) -> str:
+        return "[" + ",".join(repr(float(x)) for x in vector) + "]"
+
+    def _filter(self, side: Side) -> sql.Composable:
+        if self.partial:
+            return sql.SQL("{} IS NOT NULL AND {} IS NOT NULL").format(
+                self.columns["old"], self.columns["new"]
+            )
+        return sql.SQL("{} IS NOT NULL").format(self.columns[side])
+
+    def _query(
+        self, side: Side, *, where: sql.Composable | None, select: sql.Composable
+    ) -> sql.Composed:
+        clause = sql.SQL(" WHERE {}").format(where) if where is not None else sql.SQL("")
+        return sql.SQL(
+            "SELECT {select} FROM {table}{where} ORDER BY {col} {op} %s::{type} LIMIT %s"
+        ).format(
+            select=select,
+            table=self.table,
+            where=clause,
+            col=self.columns[side],
+            op=self.operator,
+            type=self.types[side],
+        )
+
+    # --- rows
+
+    def sample(self, text: str, size: int) -> list[tuple[str, str]]:
+        """Up to ``size`` (key, text) rows spread across the table, with both vectors."""
+        text_id = sql.Identifier(text)
+        estimate = self._run(
+            sql.SQL("SELECT reltuples::bigint FROM pg_class WHERE oid = %s::regclass"),
+            (self.table.as_string(self.conn),),
+            {},
+        )
+        rows_estimate = int(estimate[0][0]) if estimate and estimate[0][0] > 0 else 0
+        tablesample: sql.Composable = sql.SQL("")
+        if rows_estimate > size * 4:
+            percent = min(100.0, 100.0 * size * 4 / rows_estimate)
+            tablesample = sql.SQL(" TABLESAMPLE SYSTEM ({}) REPEATABLE (7)").format(
+                sql.Literal(percent)
+            )
+        query = sql.SQL(
+            "SELECT {pk}::text, {t}::text FROM {table}{ts} WHERE {both} AND {t} IS NOT NULL "
+            "AND btrim({t}::text) <> '' ORDER BY md5({pk}::text) LIMIT %s"
+        ).format(
+            pk=self.pk,
+            t=text_id,
+            table=self.table,
+            ts=tablesample,
+            both=sql.SQL("{} IS NOT NULL AND {} IS NOT NULL").format(
+                self.columns["old"], self.columns["new"]
+            ),
+        )
+        return [(str(k), str(t)) for k, t in self._run(query, (size,), {})]
+
+    def texts(self, text: str, keys: Sequence[str]) -> dict[str, str]:
+        """The text of the given rows, by key."""
+        if not keys:
+            return {}
+        query = sql.SQL(
+            "SELECT {pk}::text, {t}::text FROM {table} WHERE {pk}::text = ANY(%s)"
+        ).format(pk=self.pk, t=sql.Identifier(text), table=self.table)
+        return {str(k): str(t or "") for k, t in self._run(query, (list(keys),), {})}
+
+    # --- searches
+
+    def _select(self, side: Side) -> sql.Composable:
+        return sql.SQL("{pk}::text, ({col} {op} %s::{type})::float8").format(
+            pk=self.pk, col=self.columns[side], op=self.operator, type=self.types[side]
+        )
+
+    def search(
+        self, side: Side, vector: Sequence[float], k: int, setting: int | None = None
+    ) -> list[tuple[str, float]]:
+        """Top ``k`` (key, distance) through the index, as the application's queries run."""
+        settings = {}
+        method = self.index(side)[0]
+        if setting is not None and method:
+            settings[SETTINGS[method]] = str(int(setting))
+        literal = self._literal(vector)
+        query = self._query(side, where=None, select=self._select(side))
+        rows = self._run(query, (literal, literal, k), settings)
+        return [(str(r[0]), float(r[1])) for r in rows]
+
+    def exact(self, side: Side, vector: Sequence[float], k: int) -> list[tuple[str, float]]:
+        """Top ``k`` (key, distance) by scanning every row: what an index approximates."""
+        literal = self._literal(vector)
+        query = self._query(side, where=self._filter(side), select=self._select(side))
+        settings = {"enable_indexscan": "off", "enable_bitmapscan": "off"}
+        rows = self._run(query, (literal, literal, k), settings)
+        return [(str(r[0]), float(r[1])) for r in rows]
+
+    def index(self, side: Side) -> tuple[str | None, int | None, list[int]]:
+        """The ANN index on a side's column, its current search setting, and a sweep."""
+        if side in self._indexes:
+            return self._indexes[side]
+        rows = self._run(
+            sql.SQL(
+                """
+                SELECT am.amname, opc.opcname FROM pg_index i
+                JOIN pg_class ic ON ic.oid = i.indexrelid
+                JOIN pg_am am ON am.oid = ic.relam
+                JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = i.indkey[0]
+                JOIN pg_opclass opc ON opc.oid = i.indclass[0]
+                WHERE i.indrelid = %s::regclass AND a.attname = %s AND i.indisvalid
+                  AND am.amname IN ('hnsw', 'ivfflat')
+                """
+            ),
+            (self.table.as_string(self.conn), self.names[side]),
+            {},
+        )
+        suffix = OPCLASS_SUFFIX[self.metric]
+        method = next((str(r[0]) for r in rows if str(r[1]).endswith(suffix)), None)
+        if method is None:
+            self._indexes[side] = (None, None, [])
+            return self._indexes[side]
+        current_row = self._run(
+            sql.SQL("SELECT current_setting(%s, true)"), (SETTINGS[method],), {}
+        )
+        raw = current_row[0][0] if current_row else None
+        current = int(raw) if raw and str(raw).isdigit() else DEFAULTS[method]
+        sweep = sorted({current, *SWEEP[method]})
+        self._indexes[side] = (method, current, sweep)
+        return self._indexes[side]
+
+    def neighbours(self, side: Side, key: str, k: int) -> tuple[str | None, list[tuple[str, str]]]:
+        """A row's own group and its ``k`` nearest other rows, using that row's stored vector."""
+        own = self._run(
+            sql.SQL("SELECT {col}::text, ({group})::text FROM {table} WHERE {pk} = %s").format(
+                col=self.columns[side], group=self.group, table=self.table, pk=self.pk
+            ),
+            (key,),
+            {},
+        )
+        if not own or own[0][0] is None:
+            return None, []
+        vector, group = own[0]
+        where = sql.SQL("{} <> %s AND {}").format(self.pk, self._filter(side))
+        query = sql.SQL(
+            "SELECT {pk}::text, ({group})::text FROM {table} WHERE {where} "
+            "ORDER BY {col} {op} %s::{type} LIMIT %s"
+        ).format(
+            pk=self.pk,
+            group=self.group,
+            table=self.table,
+            where=where,
+            col=self.columns[side],
+            op=self.operator,
+            type=self.types[side],
+        )
+        settings = {"enable_indexscan": "off", "enable_bitmapscan": "off"} if self.partial else {}
+        rows = self._run(query, (key, vector, k), settings)
+        return group, [(str(r[0]), r[1]) for r in rows]
+
+    def vectors(self, side: Side, keys: Sequence[str]) -> list[list[float]]:
+        """Stored vectors of the given rows."""
+        if not keys:
+            return []
+        query = sql.SQL(
+            "SELECT {col}::text FROM {table} WHERE {pk}::text = ANY(%s) AND {col} IS NOT NULL"
+        ).format(col=self.columns[side], table=self.table, pk=self.pk)
+        rows = self._run(query, (list(keys),), {})
+        return [[float(x) for x in str(r[0]).strip("[]").split(",")] for r in rows]