Skip to content

Release 3.3.0: catalog lookups (search_values, get_schema_summary, resolve_names, get_join_candidates) - #31

Merged
1pxone merged 1 commit into
mainfrom
feat/catalog-lookups
Nov 12, 2026
Merged

1pxone merged 1 commit into
mainfrom
feat/catalog-lookups

Conversation

@1pxone

@1pxone 1pxone commented Nov 11, 2026

Copy link
Copy Markdown
Member

Python parity with the TypeScript SDK's catalog lookups (rush-db/javascript-sdk#5, released in 3.1.0): the reads agents use to find how values and names are actually stored before they query.

Before publishing

  • CI should pass: black, isort, ruff, mypy, pytest on 3.10–3.13.
  • Live check: run the four ai.* methods and properties.values(query=...) against RushDB Cloud and against a standalone engine. The SchemaSummary* and JoinEvidence types were copied from the TypeScript types and haven't been checked against a live response.
  • Merge order: merge before the imports and connections PR, which is versioned 3.4.0 on top of this one.
  • Tag: after merging, tag v3.3.0 to publish.

What

  • ai.search_values(text, match=, labels=, limit=, min_similarity=, case_sensitive=): where a value from a question is stored, across every property. Each match gives the label, property and record count; match="similar" finds near spellings. Calls POST /ai/values/search.
  • ai.get_schema_summary(labels=, few_values=): every label's properties with distinct counts, ranges and the values of small fields, in one read. Calls POST /ai/schema/summary.
  • ai.resolve_names(text, limit=): the real label or property behind a name that isn't in the schema. Calls POST /ai/schema/names.
  • ai.get_join_candidates(labels=, min_confidence=): how labels reference each other, with evidence. RushDB Cloud only. Calls POST /ai/schema/join-candidates.
  • properties.values(..., query=, match=, limit=, domain_on_miss=, min_similarity=): value search. The new options are keyword-only and win over the same keys in search_query. The result adds counts, distinctCount and searchMissed.
  • Types (TypedDicts, exported from rushdb and rushdb.models): SearchValuesParams, ValueMatch, ValueMatchesData, NameSuggestion, SchemaSummaryLabel, JoinCandidate, PropertyValuesSearch and ValueMatchMode.
  • README: feature table rows and a "Catalog Lookups" section.

Direct mode

  • search_values, get_schema_summary and resolve_names run on the engine (query.searchValues, describe.schemaSummary, describe.names), routed as the TypeScript SDK's direct router does.
  • get_join_candidates raises CloudOnlyError before sending anything.
  • Behaviour change: a plain limit on properties.values now reads the top values by record count, as in TypeScript. Before, direct mode ignored limit there.

Testing

  • tests/test_catalog_lookups.py (new) checks each method's route and body, default bodies, and the properties.values merge, including that the caller's dict is left unchanged.
  • tests/test_direct_mode.py covers engine routing for the three engine methods and value search, and the Cloud-only refusal.
  • black, isort, ruff and mypy pass; pytest has 133 passing, with 58 live-server tests skipped as in CI.

…solve_names, get_join_candidates)

ai.search_values(text, ...) finds where a value is stored across every
property (also near spellings with match="similar"); ai.get_schema_summary
returns every label's properties with distinct counts, ranges and the
values of small fields; ai.resolve_names maps a name that is not in the
schema to the real label or property; ai.get_join_candidates proposes how
labels reference each other, with evidence. properties.values gains value
search: query=, match=, limit=, domain_on_miss=, min_similarity=, with
counts and searchMissed in the result.

In direct mode the first three run on the engine; get_join_candidates is
RushDB Cloud only and raises CloudOnlyError before sending anything. A
plain limit on properties.values now reads the top values by record count
in direct mode, as the TypeScript SDK does.
@1pxone 1pxone closed this Nov 12, 2026
@1pxone 1pxone reopened this Nov 12, 2026
@1pxone
1pxone marked this pull request as ready for review November 12, 2026 16:35
@1pxone
1pxone merged commit c73ebc3 into main Nov 12, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant