Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 28 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"}
Expand Down
24 changes: 23 additions & 1 deletion src/rushdb/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -53,6 +66,15 @@
"SearchResult",
"Transaction",
"Property",
"PropertyValuesData",
"PropertyValuesSearch",
"ValueMatchMode",
"JoinCandidate",
"NameSuggestion",
"SchemaSummaryLabel",
"SearchValuesParams",
"ValueMatch",
"ValueMatchesData",
"Relationship",
"RelationshipDirection",
"RelationshipOptions",
Expand Down
140 changes: 139 additions & 1 deletion src/rushdb/api/ai.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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",
Expand All @@ -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,
Expand Down
67 changes: 53 additions & 14 deletions src/rushdb/api/properties.py
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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,
)
4 changes: 4 additions & 0 deletions src/rushdb/direct/capabilities.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading
Loading