From 97e2dc10fc74346cb035e1dd1fec4743f1c1367a Mon Sep 17 00:00:00 2001 From: Artemiy Vereshchinskiy Date: Thu, 12 Nov 2026 03:25:06 +0700 Subject: [PATCH] Release 3.3.0: catalog lookups (search_values, get_schema_summary, resolve_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. --- README.md | 30 +++++- pyproject.toml | 2 +- src/rushdb/__init__.py | 24 ++++- src/rushdb/api/ai.py | 140 +++++++++++++++++++++++++++- src/rushdb/api/properties.py | 67 +++++++++++--- src/rushdb/direct/capabilities.py | 4 + src/rushdb/direct/router.py | 97 +++++++++++++++---- src/rushdb/models/__init__.py | 24 ++++- src/rushdb/models/catalog.py | 142 ++++++++++++++++++++++++++++ src/rushdb/models/property.py | 28 ++++++ tests/test_catalog_lookups.py | 149 ++++++++++++++++++++++++++++++ tests/test_direct_mode.py | 81 ++++++++++++++++ uv.lock | 2 +- 13 files changed, 753 insertions(+), 37 deletions(-) create mode 100644 src/rushdb/models/catalog.py create mode 100644 tests/test_catalog_lookups.py diff --git a/README.md b/README.md index d97ce7c..0ff4d16 100755 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ The SDK works with RushDB in one of two ways: | Connect with | an API key | the engine URL and the engine token | The engine is what you can self-host. RushDB Cloud runs that engine for you and adds the dashboard, -managed embeddings and the AI features (natural-language search, relationship-pattern suggestions), +managed embeddings and the AI features (natural-language search, relationship-pattern and join suggestions), which exist only in RushDB Cloud. ```python @@ -85,11 +85,12 @@ What each offers: | External vector indexes; vector search with a `queryVector` you supply | ✓ | ✓ | | Raw openCypher (`query.raw`; the engine needs `--languages cypher`) | ✓ | ✓ | | Schema (`ai.get_schema`, `ai.get_schema_markdown`) | ✓ | ✓ | +| Catalog lookups: `ai.search_values` (a value across every property, also near spellings), `ai.get_schema_summary`, `ai.resolve_names`, and value search in `properties.values` (`query`, `match`, `domain_on_miss`) | ✓ | ✓ | | Keyword (BM25) search (`records.text_search`), text indexes (`text_indexes.*`), hybrid search | ✓ | ✓ | | Transactions | ✓ | record creates, updates, sets, deletes by id, attaches and imports are staged; other writes refuse a transaction | | Managed embeddings: managed indexes, `records.vector_search` by text `query` | ✓ | — | | Natural-language search on SQL (`ai.search`, `ai.run_sql`) | ✓ | — | -| Relationship-pattern suggestions (`relationships.patterns.*`) | ✓ | — | +| Relationship-pattern suggestions (`relationships.patterns.*`) and join suggestions (`ai.get_join_candidates`) | ✓ | — | | Project settings (`settings.get`), dashboard, team access | ✓ | — | In direct mode a Cloud-only method raises `CloudOnlyError` (with `method` and `reason`) before @@ -344,6 +345,31 @@ results = db.records.vector_search({ }) ``` +## Catalog Lookups + +Map the words of a question to what the data actually stores before building a +query. Each is one read of the live catalog: + +```python +# Where is a value stored? Every property, with label, property and record count +found = db.ai.search_values('spiderman', match='similar') # contains | prefix | exact | similar +for m in found.data['matches']: + print(m['label'], m['property'], m['value'], m['count']) + +# Every label with its properties, distinct counts, ranges and the values of small fields +summary = db.ai.get_schema_summary(labels=['Patient'], few_values=10) + +# The real label or property behind a name that is not in the schema +db.ai.resolve_names('patients.birthdate') # -> Patient.Birthday + +# Value search within one property: ranked by record count, with counts; +# when nothing matches, list the whole domain of a small property +db.properties.values(property_id, query='positive', domain_on_miss=20) + +# How labels reference each other, with evidence (RushDB Cloud only) +db.ai.get_join_candidates(labels=['Order'], min_confidence=0.5) +``` + --- ## Record API diff --git a/pyproject.toml b/pyproject.toml index 44395be..a687121 100755 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "rushdb" -version = "3.2.1" +version = "3.3.0" description = "RushDB SDK for Python: the client for RushDB, the database for AI (RushDB Cloud or self-hosted)" authors = [ {name = "RushDB Team", email = "hi@rushdb.com"} diff --git a/src/rushdb/__init__.py b/src/rushdb/__init__.py index 3cace8d..84694d9 100755 --- a/src/rushdb/__init__.py +++ b/src/rushdb/__init__.py @@ -17,7 +17,20 @@ is_cloud_only_method, ) from .models.api_response import ApiResponse -from .models.property import Property +from .models.catalog import ( + JoinCandidate, + NameSuggestion, + SchemaSummaryLabel, + SearchValuesParams, + ValueMatch, + ValueMatchesData, +) +from .models.property import ( + Property, + PropertyValuesData, + PropertyValuesSearch, + ValueMatchMode, +) from .models.record import Record, RecordTarget, RelationTarget from .models.relationship import ( Relationship, @@ -53,6 +66,15 @@ "SearchResult", "Transaction", "Property", + "PropertyValuesData", + "PropertyValuesSearch", + "ValueMatchMode", + "JoinCandidate", + "NameSuggestion", + "SchemaSummaryLabel", + "SearchValuesParams", + "ValueMatch", + "ValueMatchesData", "Relationship", "RelationshipDirection", "RelationshipOptions", diff --git a/src/rushdb/api/ai.py b/src/rushdb/api/ai.py index 7917bf1..c415624 100755 --- a/src/rushdb/api/ai.py +++ b/src/rushdb/api/ai.py @@ -5,9 +5,16 @@ """ import warnings -from typing import TYPE_CHECKING, Any, Dict, Optional, Union +from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union from ..models.api_response import ApiResponse +from ..models.catalog import ( + JoinCandidate, + NameSuggestion, + SchemaSummaryLabel, + ValueMatchesData, +) +from ..models.property import ValueMatchMode from ..models.record import Record from ..models.result import RecordSearchResult from ..models.transaction import Transaction @@ -126,6 +133,7 @@ class AIAPI(BaseAPI): >>> db = RushDB(api_key="...") >>> schema = db.ai.get_schema() + >>> found = db.ai.search_values("spiderman", match="similar") >>> results = db.ai.search("books about fast cars") >>> vectors = db.records.vector_search({ ... "query": "fast cars", @@ -139,6 +147,136 @@ def __init__(self, client: "RushDB"): super().__init__(client) self.indexes = _AIIndexesNamespace(client) + def _catalog_read(self, path: str, body: Dict[str, Any]) -> ApiResponse: + response = self.client._make_request("POST", path, body) + return ApiResponse( + data=response.get("data"), + success=response.get("success", True), + total=response.get("total"), + ) + + def search_values( + self, + text: str, + match: Optional[ValueMatchMode] = None, + labels: Optional[List[str]] = None, + limit: Optional[int] = None, + min_similarity: Optional[float] = None, + case_sensitive: Optional[bool] = None, + ) -> "ApiResponse[ValueMatchesData]": + """Find stored values matching a text across every property. + + Each match names the label and property holding the value and its + record count. It maps a word in a question to the value the data + actually stores (``"positive"`` to ``KCT = "+"`` once combined with + :meth:`get_schema_summary`). + + Args: + text: The text to look for. + match: ``"contains"`` (default), ``"prefix"``, ``"exact"`` or + ``"similar"`` for near spellings (``spiderman`` finds + ``Spider-Man``). + labels: Labels to search (all when omitted). + limit: Most matches (default 50, at most 1000). + min_similarity: ``"similar"`` only: least similarity, 0 to 1 + (default 0.6). + case_sensitive: Match case exactly (default ``False``). + + Returns: + ApiResponse: ``data`` holds ``matches`` (each ``label``, + ``property``, ``value``, ``count``), ``total`` (matches before + ``limit``) and, when some properties could not be searched within + the request limits, ``skipped`` as ``label.property``. + """ + body: Dict[str, Any] = {"text": text} + if match is not None: + body["match"] = match + if case_sensitive is not None: + body["caseSensitive"] = case_sensitive + if min_similarity is not None: + body["minSimilarity"] = min_similarity + if labels is not None: + body["labels"] = labels + if limit is not None: + body["limit"] = limit + return self._catalog_read("/ai/values/search", body) + + def get_schema_summary( + self, + labels: Optional[List[str]] = None, + few_values: Optional[int] = None, + ) -> "ApiResponse[List[SchemaSummaryLabel]]": + """Every label with its properties in one read, from the live catalog. + + Types, record and exact distinct counts, numeric and date ranges, the + values of properties that hold few, and relationship shapes. + + Args: + labels: Labels to summarize (all when omitted). + few_values: List a property's values when it holds at most this + many (default 10). + + Returns: + ApiResponse: ``data`` is a list of labels, each with ``name``, + ``recordsCount``, ``properties`` and ``relationships``. + """ + body: Dict[str, Any] = {} + if labels is not None: + body["labels"] = labels + if few_values is not None: + body["fewValues"] = few_values + return self._catalog_read("/ai/schema/summary", body) + + def resolve_names( + self, text: str, limit: Optional[int] = None + ) -> "ApiResponse[List[NameSuggestion]]": + """Labels and properties spelled like a name. + + Ignores case, separators and plural endings: the answer to "no such + label or property" (``patients.birthdate`` to ``Patient.Birthday``). + + Args: + text: The name, optionally as ``Label.property``. + limit: Most suggestions. + + Returns: + ApiResponse: ``data`` is a list of suggestions, each with + ``label``, ``property`` (for a property) and ``score`` (spelling + similarity, 0 to 1). + """ + body: Dict[str, Any] = {"text": text} + if limit is not None: + body["limit"] = limit + return self._catalog_read("/ai/schema/names", body) + + def get_join_candidates( + self, + labels: Optional[List[str]] = None, + min_confidence: Optional[float] = None, + ) -> "ApiResponse[List[JoinCandidate]]": + """Properties that look like references to another label's key. + + Found from property names and exact value containment (no language + model), each with its evidence. RushDB Cloud only: in direct mode it + raises :class:`~rushdb.common.CloudOnlyError`. + + Args: + labels: Labels the candidates must touch (all when omitted). + min_confidence: Least confidence, 0 to 1 (default 0.5). + + Returns: + ApiResponse: ``data`` is a list of candidates, each with + ``source`` and ``target`` (``label``, ``property``), ``reasons``, + ``relationshipType``, ``confidence``, ``evidence`` and + ``rationale``. + """ + body: Dict[str, Any] = {} + if labels is not None: + body["labels"] = labels + if min_confidence is not None: + body["minConfidence"] = min_confidence + return self._catalog_read("/ai/schema/join-candidates", body) + def get_schema( self, params: Optional[Dict[str, Any]] = None, diff --git a/src/rushdb/api/properties.py b/src/rushdb/api/properties.py index 7dd9464..b85931f 100755 --- a/src/rushdb/api/properties.py +++ b/src/rushdb/api/properties.py @@ -1,25 +1,33 @@ import typing from typing import List, Optional -from ..models.property import Property, PropertyValuesData +from ..models.property import ( + Property, + PropertyValuesData, + PropertyValuesSearch, + ValueMatchMode, +) from ..models.search_query import SearchQuery from ..models.transaction import Transaction from .base import BaseAPI -class PropertyValuesQuery(SearchQuery, total=False): - """Extended SearchQuery for property values endpoint with text search support. - - This class extends the base SearchQuery to include additional search capabilities - specifically for querying property values, including text-based search functionality. +class PropertyValuesQuery(SearchQuery, PropertyValuesSearch, total=False): + """Extended SearchQuery for property values endpoint with value search. Attributes: - query (Optional[str]): Text search string to filter property values. - When provided, performs a text-based search among the property values. + query (Optional[str]): Keep the values whose text matches; the values + then rank by record count and come with ``counts``. + match (str): How ``query`` matches: ``contains`` (default), ``prefix``, + ``exact`` or ``similar`` for near spellings. + limit (Optional[int]): Most values returned, by record count (default + 100 with ``query``). + domainOnMiss (int): With no match, list every value of a property + holding at most this many (``searchMissed: True``). + minSimilarity (float): ``similar`` only: least similarity, 0 to 1 + (default 0.6). """ - query: Optional[str] # For text search among values - class PropertiesAPI(BaseAPI): """API client for managing properties in RushDB. @@ -168,12 +176,18 @@ def values( property_id: str, search_query: Optional[PropertyValuesQuery] = None, transaction: Optional[Transaction] = None, + *, + query: Optional[str] = None, + match: Optional[ValueMatchMode] = None, + limit: Optional[int] = None, + domain_on_miss: Optional[int] = None, + min_similarity: Optional[float] = None, ) -> PropertyValuesData: """Retrieve and search values data for a specific property. Gets statistical and analytical data about the values stored in a particular property, - including value distributions, counts, and other metadata. Supports text-based - searching within the property values. + including value distributions, counts, and other metadata. A ``query`` applies as a + value search: the values whose text matches, ranked by record count, with ``counts``. Args: property_id (str): The unique identifier of the property to analyze. @@ -184,10 +198,21 @@ def values( Defaults to None. transaction (Optional[Transaction], optional): Transaction context for the operation. If provided, the operation will be part of the transaction. Defaults to None. + query (Optional[str]): Keep the values whose text matches. Overrides + ``search_query["query"]``, as do the options below their keys. + match (Optional[str]): ``contains`` (default), ``prefix``, ``exact`` or + ``similar`` for near spellings. + limit (Optional[int]): Most values returned, by record count (default 100 + with ``query``). + domain_on_miss (Optional[int]): With no match, list every value of a property + holding at most this many; the result then has ``searchMissed: True``. + min_similarity (Optional[float]): ``similar`` only: least similarity, 0 to 1 + (default 0.6). Returns: PropertyValuesData: Object containing statistical and analytical data about - the property's values, including distributions, counts, and value samples. + the property's values; a searched or limited read adds ``counts`` (aligned + with ``values``) and ``distinctCount`` (matches before ``limit``). Raises: ValueError: If the property_id is invalid or empty. @@ -204,12 +229,26 @@ def values( >>> # Search for specific values >>> query = PropertyValuesQuery(query="search_text") >>> filtered_values = properties_api.values("prop_123", query) + >>> + >>> # How "positive" is stored, with the whole domain when nothing matches + >>> properties_api.values("prop_123", query="positive", domain_on_miss=20) """ headers = Transaction._build_transaction_header(transaction) + body: typing.Dict[str, typing.Any] = dict(search_query or {}) + for key, value in ( + ("query", query), + ("match", match), + ("limit", limit), + ("domainOnMiss", domain_on_miss), + ("minSimilarity", min_similarity), + ): + if value is not None: + body[key] = value + return self.client._make_request( "POST", f"/properties/{property_id}/values", - typing.cast(typing.Dict[str, typing.Any], search_query or {}), + body, headers, ) diff --git a/src/rushdb/direct/capabilities.py b/src/rushdb/direct/capabilities.py index 04ed11f..d0fef88 100644 --- a/src/rushdb/direct/capabilities.py +++ b/src/rushdb/direct/capabilities.py @@ -12,6 +12,10 @@ CLOUD_ONLY_METHODS: Dict[str, str] = { "ai.search": "natural-language search turns the prompt into a SQL statement with an LLM", "ai.run_sql": "Smart search SQL runs on the platform, which loads the full records the statement selects", + "ai.get_join_candidates": ( + "join suggestions are computed by the platform " + "(its heuristics over the engine's value overlap)" + ), "relationships.patterns.list": _PATTERNS, "relationships.patterns.analyze": _PATTERNS, "relationships.patterns.approve": _PATTERNS, diff --git a/src/rushdb/direct/router.py b/src/rushdb/direct/router.py index ae35e46..df3b637 100644 --- a/src/rushdb/direct/router.py +++ b/src/rushdb/direct/router.py @@ -899,22 +899,78 @@ def _delete_property(request: _Request) -> Body: def _property_values(request: _Request) -> Body: body = request.body - result = request.engine.execute( - { - "kind": "query", - "query": { - "kind": "propertyValues", - "property": request.params[0], - "query": query_document( - { - "labels": body.get("labels") or [], - "where": body.get("where") or {}, - } - ), - }, - } - ) - return _ok({"values": result.get("values") or []}) + searched = bool(body.get("query")) or bool(body.get("limit")) + query: Body = { + "kind": "propertyValues", + "property": request.params[0], + "query": query_document( + { + "labels": body.get("labels") or [], + "where": body.get("where") or {}, + } + ), + } + if searched: + query["mode"] = "topK" + query["limit"] = body.get("limit") or 100 + if body.get("query"): + search: Body = {"text": body["query"], "match": body.get("match") or "contains"} + if body.get("domainOnMiss"): + search["domainOnMiss"] = body["domainOnMiss"] + if body.get("minSimilarity") is not None: + search["minSimilarity"] = body["minSimilarity"] + query["search"] = search + result = request.engine.execute({"kind": "query", "query": query}) + data: Body = {"values": result.get("values") or []} + if result.get("counts"): + data["counts"] = result["counts"] + if searched and result.get("distinctCount") is not None: + data["distinctCount"] = result["distinctCount"] + if result.get("searchMissed"): + data["searchMissed"] = True + return _ok(data) + + +def _search_values(request: _Request) -> Body: + body = request.body + search: Body = {"text": body.get("text"), "match": body.get("match") or "contains"} + if body.get("caseSensitive"): + search["caseSensitive"] = True + if body.get("minSimilarity") is not None: + search["minSimilarity"] = body["minSimilarity"] + query: Body = {"kind": "searchValues", "search": search} + if body.get("labels"): + query["labels"] = body["labels"] + if body.get("limit"): + query["limit"] = body["limit"] + result = request.engine.execute({"kind": "query", "query": query}) + data: Body = { + "matches": result.get("matches") or [], + "total": result.get("total") or 0, + } + if result.get("skipped"): + data["skipped"] = result["skipped"] + return _ok(data) + + +def _schema_summary(request: _Request) -> Body: + body = request.body + describe: Body = {"kind": "schemaSummary"} + if body.get("labels"): + describe["labels"] = body["labels"] + if body.get("fewValues") is not None: + describe["fewValues"] = body["fewValues"] + result = request.engine.execute({"kind": "describe", "describe": describe}) + return _ok(result.get("labels") or []) + + +def _resolve_names(request: _Request) -> Body: + body = request.body + describe: Body = {"kind": "names", "text": body.get("text")} + if body.get("limit"): + describe["limit"] = body["limit"] + result = request.engine.execute({"kind": "describe", "describe": describe}) + return _ok(result.get("names") or []) def _find_labels(request: _Request) -> Body: @@ -1395,6 +1451,15 @@ def _drop_vector_index(request: _Request) -> Body: ) ), ), + # catalog reads; join suggestions are Cloud-only + ("POST", re.compile(r"^/ai/values/search$"), _search_values), + ("POST", re.compile(r"^/ai/schema/summary$"), _schema_summary), + ("POST", re.compile(r"^/ai/schema/names$"), _resolve_names), + ( + "POST", + re.compile(r"^/ai/schema/join-candidates$"), + _cloud_only("ai.get_join_candidates"), + ), ("GET", re.compile(r"^/text-indexes$"), lambda r: _ok(_text_indexes(r.engine))), ("POST", re.compile(r"^/text-indexes$"), _create_text_index), ( diff --git a/src/rushdb/models/__init__.py b/src/rushdb/models/__init__.py index a9b047f..f169572 100755 --- a/src/rushdb/models/__init__.py +++ b/src/rushdb/models/__init__.py @@ -1,4 +1,17 @@ -from .property import Property +from .catalog import ( + JoinCandidate, + NameSuggestion, + SchemaSummaryLabel, + SearchValuesParams, + ValueMatch, + ValueMatchesData, +) +from .property import ( + Property, + PropertyValuesData, + PropertyValuesSearch, + ValueMatchMode, +) from .record import Record from .relationship import ( Relationship, @@ -19,6 +32,15 @@ __all__ = [ "Property", + "PropertyValuesData", + "PropertyValuesSearch", + "ValueMatchMode", + "JoinCandidate", + "NameSuggestion", + "SchemaSummaryLabel", + "SearchValuesParams", + "ValueMatch", + "ValueMatchesData", "Record", "Relationship", "RelationshipDetachOptions", diff --git a/src/rushdb/models/catalog.py b/src/rushdb/models/catalog.py new file mode 100644 index 0000000..fe94f74 --- /dev/null +++ b/src/rushdb/models/catalog.py @@ -0,0 +1,142 @@ +"""Catalog lookups: the shapes of ``db.ai.search_values``, +``db.ai.get_schema_summary``, ``db.ai.resolve_names`` and +``db.ai.get_join_candidates``.""" + +from typing import List, Literal, TypedDict + +from .property import PropertyValue, ValueMatchMode + + +class _SearchValuesParamsRequired(TypedDict): + text: str + + +class SearchValuesParams(_SearchValuesParamsRequired, total=False): + """Body of ``db.ai.search_values`` (``POST /ai/values/search``).""" + + match: ValueMatchMode + caseSensitive: bool + minSimilarity: float + labels: List[str] + """Labels to search (all when omitted).""" + limit: int + """Most matches (default 50, at most 1000).""" + + +class ValueMatch(TypedDict): + """A stored value matching ``db.ai.search_values``, with where it is held.""" + + label: str + property: str + value: PropertyValue + count: int + + +class _ValueMatchesDataRequired(TypedDict): + matches: List[ValueMatch] + total: int + """Matches before ``limit``.""" + + +class ValueMatchesData(_ValueMatchesDataRequired, total=False): + """``data`` of ``db.ai.search_values``.""" + + skipped: List[str] + """Properties that could not be searched within the request limits, as + ``label.property``.""" + + +class _NameSuggestionRequired(TypedDict): + label: str + score: float + """Spelling similarity, 0 to 1.""" + + +class NameSuggestion(_NameSuggestionRequired, total=False): + """A label or property spelled like a requested name (``db.ai.resolve_names``).""" + + property: str + + +class _SchemaSummaryPropertyRequired(TypedDict): + name: str + type: str + recordsCount: int + + +class SchemaSummaryProperty(_SchemaSummaryPropertyRequired, total=False): + """One property of a :class:`SchemaSummaryLabel`.""" + + isArray: bool + distinctCount: int + min: PropertyValue + max: PropertyValue + values: List[PropertyValue] + """Every value, by record count, when the property holds few.""" + + +class SchemaSummaryRelationship(TypedDict): + """One relationship shape of a :class:`SchemaSummaryLabel`.""" + + type: str + label: str + direction: Literal["in", "out"] + count: int + + +class _SchemaSummaryLabelRequired(TypedDict): + name: str + recordsCount: int + properties: List[SchemaSummaryProperty] + + +class SchemaSummaryLabel(_SchemaSummaryLabelRequired, total=False): + """One label of ``db.ai.get_schema_summary``.""" + + relationships: List[SchemaSummaryRelationship] + + +class JoinEndpoint(TypedDict): + """One side of a :class:`JoinCandidate`.""" + + label: str + property: str + + +class JoinEvidence(TypedDict, total=False): + """What a :class:`JoinCandidate` rests on.""" + + sourceDistinct: int + targetDistinct: int + matchedDistinct: int + matchedRecords: int + coverage: float + targetUniqueness: float + notCompared: str + + +class JoinCandidate(TypedDict): + """A reference suggested by ``db.ai.get_join_candidates``, with its evidence.""" + + source: JoinEndpoint + target: JoinEndpoint + reasons: List[str] + """``name``, ``chain`` and/or ``values``: the rules that proposed it.""" + relationshipType: str + confidence: float + evidence: JoinEvidence + rationale: str + + +__all__ = [ + "JoinCandidate", + "JoinEndpoint", + "JoinEvidence", + "NameSuggestion", + "SchemaSummaryLabel", + "SchemaSummaryProperty", + "SchemaSummaryRelationship", + "SearchValuesParams", + "ValueMatch", + "ValueMatchesData", +] diff --git a/src/rushdb/models/property.py b/src/rushdb/models/property.py index 543eb5c..354b228 100755 --- a/src/rushdb/models/property.py +++ b/src/rushdb/models/property.py @@ -25,6 +25,9 @@ class DatetimeObject(TypedDict, total=False): # input value in `PropertyWithValue.value` below. PropertyType = Literal["boolean", "datetime", "number", "string"] +PropertyValue = Union[DatetimeValue, BooleanValue, None, NumberValue, StringValue] +"""One stored value of a property.""" + class Property(TypedDict): """Base property structure""" @@ -55,3 +58,28 @@ class PropertyValuesData(TypedDict, total=False): max: Optional[float] min: Optional[float] values: List[Any] + counts: List[int] + """Record counts aligned with ``values`` (a searched or ``limit``-ed read).""" + distinctCount: int + """Distinct values matching the search, before ``limit``.""" + searchMissed: bool + """The search matched nothing and ``values`` lists the whole (small) domain + (``domainOnMiss``).""" + + +ValueMatchMode = Literal["contains", "prefix", "exact", "similar"] +"""How a value search matches stored values. ``similar`` finds near spellings.""" + + +class PropertyValuesSearch(TypedDict, total=False): + """Value-search options for ``db.properties.values``.""" + + query: Optional[str] + """Keep the values whose text matches.""" + match: ValueMatchMode + limit: Optional[int] + """Most values returned, by record count (default 100 with ``query``).""" + domainOnMiss: int + """With no match, list every value of a property holding at most this many.""" + minSimilarity: float + """``similar`` only: least similarity, 0 to 1 (default 0.6).""" diff --git a/tests/test_catalog_lookups.py b/tests/test_catalog_lookups.py new file mode 100644 index 0000000..3139d5a --- /dev/null +++ b/tests/test_catalog_lookups.py @@ -0,0 +1,149 @@ +"""Catalog lookups send their bodies to the platform routes the TypeScript SDK +uses, with snake_case options as camelCase keys and unset ones left out.""" + +import unittest +from unittest.mock import Mock + +from rushdb.api.ai import AIAPI +from rushdb.api.properties import PropertiesAPI +from rushdb.models.api_response import ApiResponse + + +def _client(data): + client = Mock() + client._make_request.return_value = {"success": True, "data": data} + return client + + +class TestCatalogLookups(unittest.TestCase): + def test_search_values_posts_the_search(self): + data = { + "matches": [ + {"label": "Hero", "property": "name", "value": "Spider-Man", "count": 3} + ], + "total": 1, + } + client = _client(data) + + result = AIAPI(client).search_values( + "spiderman", + match="similar", + labels=["Hero"], + limit=5, + min_similarity=0.7, + case_sensitive=True, + ) + + client._make_request.assert_called_once_with( + "POST", + "/ai/values/search", + { + "text": "spiderman", + "match": "similar", + "caseSensitive": True, + "minSimilarity": 0.7, + "labels": ["Hero"], + "limit": 5, + }, + ) + self.assertIsInstance(result, ApiResponse) + self.assertEqual(result.data, data) + + def test_search_values_sends_only_the_text_by_default(self): + client = _client({"matches": [], "total": 0}) + AIAPI(client).search_values("positive") + client._make_request.assert_called_once_with( + "POST", "/ai/values/search", {"text": "positive"} + ) + + def test_get_schema_summary_posts_labels_and_few_values(self): + client = _client([{"name": "Patient", "recordsCount": 2, "properties": []}]) + + result = AIAPI(client).get_schema_summary(labels=["Patient"], few_values=5) + + client._make_request.assert_called_once_with( + "POST", "/ai/schema/summary", {"labels": ["Patient"], "fewValues": 5} + ) + self.assertEqual(result.data[0]["name"], "Patient") + + def test_get_schema_summary_without_options_posts_an_empty_body(self): + client = _client([]) + AIAPI(client).get_schema_summary() + client._make_request.assert_called_once_with("POST", "/ai/schema/summary", {}) + + def test_resolve_names_posts_the_name(self): + client = _client([{"label": "Patient", "property": "Birthday", "score": 0.9}]) + + result = AIAPI(client).resolve_names("patients.birthdate", limit=3) + + client._make_request.assert_called_once_with( + "POST", "/ai/schema/names", {"text": "patients.birthdate", "limit": 3} + ) + self.assertEqual(result.data[0]["property"], "Birthday") + + def test_get_join_candidates_posts_labels_and_min_confidence(self): + candidate = { + "source": {"label": "Order", "property": "customerId"}, + "target": {"label": "Customer", "property": "id"}, + "reasons": ["name", "values"], + "relationshipType": "CUSTOMER", + "confidence": 0.9, + "evidence": {"coverage": 1.0}, + "rationale": "customerId values are Customer ids", + } + client = _client([candidate]) + + result = AIAPI(client).get_join_candidates(labels=["Order"], min_confidence=0.8) + + client._make_request.assert_called_once_with( + "POST", + "/ai/schema/join-candidates", + {"labels": ["Order"], "minConfidence": 0.8}, + ) + self.assertEqual(result.data, [candidate]) + + def test_property_values_sends_the_value_search(self): + client = _client({"values": ["+"], "counts": [4]}) + + PropertiesAPI(client).values( + "prop-1", + {"labels": ["Test"], "orderBy": "desc"}, + query="positive", + match="contains", + limit=10, + domain_on_miss=20, + min_similarity=0.5, + ) + + client._make_request.assert_called_once_with( + "POST", + "/properties/prop-1/values", + { + "labels": ["Test"], + "orderBy": "desc", + "query": "positive", + "match": "contains", + "limit": 10, + "domainOnMiss": 20, + "minSimilarity": 0.5, + }, + None, + ) + + def test_property_values_keeps_a_search_query_dict(self): + client = _client({"values": []}) + search_query = {"query": "pos", "domainOnMiss": 5} + + PropertiesAPI(client).values("prop-1", search_query) + + client._make_request.assert_called_once_with( + "POST", + "/properties/prop-1/values", + {"query": "pos", "domainOnMiss": 5}, + None, + ) + self.assertEqual(search_query, {"query": "pos", "domainOnMiss": 5}) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_direct_mode.py b/tests/test_direct_mode.py index 2540fff..0f90f60 100755 --- a/tests/test_direct_mode.py +++ b/tests/test_direct_mode.py @@ -71,6 +71,26 @@ def engine_answer(operation): "property": "title", "values": ["Dune"], }, + "query.searchValues": { + "kind": "valueMatches", + "matches": [ + {"label": "Book", "property": "title", "value": "Dune", "count": 1} + ], + "total": 1, + }, + "describe.schemaSummary": { + "kind": "schemaSummary", + "labels": [ + { + "name": "Book", + "recordsCount": 1, + "properties": [ + {"name": "title", "type": "string", "recordsCount": 1} + ], + } + ], + }, + "describe.names": {"kind": "names", "names": [{"label": "Book", "score": 1}]}, "query.statement": {"kind": "rows", "rows": [{"n": 1}], "total": 1}, "query.exportCsv": { "kind": "csv", @@ -275,6 +295,10 @@ def operations(calls): ), "ai.search": lambda db: db.ai.search("books about deserts"), "ai.run_sql": lambda db: db.ai.run_sql('SELECT __id FROM "Book"'), + "ai.search_values": lambda db: db.ai.search_values("dune"), + "ai.get_schema_summary": lambda db: db.ai.get_schema_summary(), + "ai.resolve_names": lambda db: db.ai.resolve_names("books"), + "ai.get_join_candidates": lambda db: db.ai.get_join_candidates(), "settings.get": lambda db: db.settings.get(), } @@ -391,6 +415,63 @@ def test_export_returns_the_csv_text(engine_calls): ) +def test_property_values_apply_a_text_query_as_an_engine_value_search(engine_calls): + values = direct_db().properties.values("p1", query="positive", domain_on_miss=20) + query = operations(engine_calls)[0]["query"] + assert {key: value for key, value in query.items() if key != "query"} == { + "kind": "propertyValues", + "property": "p1", + "mode": "topK", + "limit": 100, + "search": {"text": "positive", "match": "contains", "domainOnMiss": 20}, + } + assert values["data"]["values"] == ["Dune"] + + +def test_property_values_without_a_search_read_every_value(engine_calls): + direct_db().properties.values("p1") + query = operations(engine_calls)[0]["query"] + assert "mode" not in query and "search" not in query + + +def test_catalog_suggestions_map_to_their_engine_reads(engine_calls): + db = direct_db() + found = db.ai.search_values("spiderman", match="similar", labels=["Book"]) + summary = db.ai.get_schema_summary(few_values=5) + names = db.ai.resolve_names("books", limit=3) + assert operations(engine_calls) == [ + { + "kind": "query", + "query": { + "kind": "searchValues", + "search": {"text": "spiderman", "match": "similar"}, + "labels": ["Book"], + }, + }, + {"kind": "describe", "describe": {"kind": "schemaSummary", "fewValues": 5}}, + { + "kind": "describe", + "describe": {"kind": "names", "text": "books", "limit": 3}, + }, + ] + assert found.data["matches"][0] == { + "label": "Book", + "property": "title", + "value": "Dune", + "count": 1, + } + assert found.data["total"] == 1 + assert summary.data[0]["name"] == "Book" + assert names.data == [{"label": "Book", "score": 1}] + + +def test_join_candidates_need_cloud(engine_calls): + with pytest.raises(CloudOnlyError) as refused: + direct_db().ai.get_join_candidates(labels=["Book"]) + assert refused.value.method == "ai.get_join_candidates" + assert engine_calls == [] + + def test_a_text_vector_search_needs_cloud(engine_calls): with pytest.raises(CloudOnlyError): direct_db().records.vector_search( diff --git a/uv.lock b/uv.lock index 7e4ce67..18cf2b7 100755 --- a/uv.lock +++ b/uv.lock @@ -710,7 +710,7 @@ wheels = [ [[package]] name = "rushdb" -version = "3.2.1" +version = "3.3.0" source = { editable = "." } [package.dev-dependencies]