flowquery 1.0.65__tar.gz → 1.0.66__tar.gz

{flowquery-1.0.65 → flowquery-1.0.66}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowquery
-Version: 1.0.65
+Version: 1.0.66
 Summary: A declarative query language for data processing pipelines
 Author-email: Team Microsoft FlowQuery <flowquery@microsoft.com>
 License: MIT
@@ -307,6 +307,147 @@ The same chain is reflected statically in `info.sources` so callers
 can introspect the upstream dependency graph without running the
 query.
 
+## Backend-Aware Virtual Sources
+
+By default a virtual definition is loaded eagerly: its sub-query runs
+once per query and all rows are held in memory. For large or remote
+backends, a **source provider** lets FlowQuery read only what a pattern
+needs. This is opt-in: existing `CREATE VIRTUAL` definitions behave
+exactly as before.
+
+The simplest way to write a provider is to subclass `NodeSource` or
+`RelationshipSource` and implement `scan(request, context)`. Implement
+`lookup` (nodes by id) or `expand` (relationships by `left_id`/`right_id`)
+when the backend can fetch selectively; the base class then declares the
+matching capability for you. `version` defaults to the current contract
+version, and capability keys may be written in snake_case
+(`max_batch_size`, `string_ordering`). A method may return a list of
+rows, an awaitable list, or an (async) iterable of pages.
+
+The `request` is a `SourceRequest`: a dict with the same camelCase keys
+as the TypeScript implementation (`request["pageSize"]`) that also
+accepts snake_case keys (`request["page_size"]`) and attribute access
+(`request.ids`, `request.side`, `request.predicate`, `request.page_size`).
+
+```python
+from flowquery import FlowQuery, NodeSource, RelationshipSource, cursor_pages
+
+class People(NodeSource):
+    capabilities = {
+        "cacheable": True,       # identical reads within one query may be cached
+        "max_batch_size": 50,    # ids per lookup/expand request
+        "predicates": {"operators": ["eq", "in", "gt", "gte", "lt", "lte"]},
+    }
+
+    def scan(self, request, context):
+        async def fetch(cursor):
+            page = await api.people(filter=request.predicate, cursor=cursor)
+            return {"rows": page.rows, "cursor": page.next_cursor}
+        return cursor_pages(fetch)
+
+    async def lookup(self, request, context):  # declares "lookup": True
+        return await api.people_by_ids(request.ids)
+
+class Knows(RelationshipSource):
+    async def scan(self, request, context):
+        return await api.all_knows()
+
+    async def expand(self, request, context):  # declares both expand sides
+        key = "from" if request.side == "left" else "to"
+        return await api.knows(**{key: request.ids})
+
+FlowQuery.register_node_source("Person", People())
+FlowQuery.register_relationship_source("KNOWS", "Person", "Person", Knows())
+
+fq = FlowQuery("MATCH (a:Person {id: 7})-[:KNOWS]->(b:Person) RETURN b.name LIMIT 10")
+await fq.run()
+print(fq.source_stats)  # calls, pages, rows, cacheHits, batches, plans...
+```
+
+Subclassing is optional: any object with a `capabilities` dict and a
+`scan` method works, and `SourceProvider` is a `typing.Protocol`
+describing that shape.
+
+The engine then loads correlated rows in batches instead of reading
+every person and relationship:
+
+- **Correlated loading and batching.** It issues id lookups, expands per
+  page of anchor nodes, and makes batched lookups for target nodes.
+- **Selective start points.** A chain may start from its more selective
+  end. The decision is recorded in `source_stats["plans"]`, and it can
+  change result order when there is no `ORDER BY`.
+- **Predicate push-down.** Pattern properties and `AND`-ed `WHERE`
+  comparisons (`=`, `<`, `<=`, `>`, `>=`, `IN`) against literals or
+  parameters are sent as `request["predicate"]`.
+- **Streaming with early stop under `LIMIT`.** Reading stops once the
+  limit is reached and the provider's iterator is closed.
+- **Query-scoped caching.**
+- **Cancellation.** Call `runner.cancel()` or pass
+  `SourceOptions(signal=...)` (an `asyncio.Event` or `SourceSignal`).
+  The query raises `QueryCancelledError`.
+- **Read contexts.** Optional `open_read_context()` and
+  `close_read_context(snapshot)` methods are called once per query.
+
+Providers may return a **superset**, because FlowQuery re-checks every
+row. `matches_predicate(predicate, row)` is a reference implementation
+of the predicate semantics.
+
+Errors are reported through typed exceptions:
+
+- `SourceCapabilityError`: an invalid declaration, raised at
+  registration.
+- `SourceResponseError`: malformed pages or a repeated cursor.
+- `SourceError`: any other provider failure.
+
+A provider may raise `SourceUnsupportedError` from `lookup`/`expand` to
+fall back to a scan.
+
+Query-level tuning goes in `RunnerOptions(sources=SourceOptions(...))`:
+`page_size` (256), `max_batch_size` (100), `cache_capacity` (10000),
+`max_prefetch_rows` (1024) and `reorder` (`True`).
+
+**In-memory sources.** `in_memory_node_source(rows)` and
+`in_memory_relationship_source(rows)` are ready-made providers over
+lists. They support lookup, expansion from both sides, every predicate
+operator and paging, which makes them handy for tests, examples and
+small reference data. Keyword options are `cacheable` (default `True`)
+and `max_batch_size`.
+
+```python
+from flowquery import in_memory_node_source, in_memory_relationship_source
+
+FlowQuery.register_node_source(
+    "Person", in_memory_node_source([{"id": 1, "name": "Ada"}, {"id": 2, "name": "Bob"}])
+)
+FlowQuery.register_relationship_source(
+    "KNOWS", "Person", "Person", in_memory_relationship_source([{"left_id": 1, "right_id": 2}])
+)
+```
+
+**Statement-backed sources.** A `CREATE VIRTUAL` definition can opt into
+the same contract declaratively with a `WITH CAPABILITIES { ... }` clause
+between the pattern and `AS`. Each request runs its sub-query with
+`$request` bound to the request (`operation`, `label`/`type`, `ids`,
+`side`, `predicate`, `pageSize`):
+
+```python
+await FlowQuery("""
+    CREATE VIRTUAL (:Ticket) WITH CAPABILITIES {lookup: true, streaming: true} AS {
+        LOAD JSON FROM f"https://api.example.com/tickets?ids={join(coalesce($request.ids, []), ',')}" AS t
+        RETURN t.id AS id, t.title AS title
+    }
+""").run()
+```
+
+The map takes the same (camelCase) keys as the capabilities dict;
+`version` defaults to the current contract version. Invalid capabilities
+reject the whole definition. Redefining the label without
+`WITH CAPABILITIES`, or deleting it, restores eager loading. The same
+opt-in is available programmatically with
+`FlowQuery.set_node_source_capabilities(label, capabilities)` and
+`FlowQuery.set_relationship_source_capabilities(...)`; pass `None` to
+opt out.
+
 ## Documentation
 
 - [Language Reference](https://github.com/microsoft/FlowQuery#language-reference) (clauses, expressions, functions, graph operations, and more)

{flowquery-1.0.65 → flowquery-1.0.66}/README.md

@@ -274,6 +274,147 @@ The same chain is reflected statically in `info.sources` so callers
 can introspect the upstream dependency graph without running the
 query.
 
+## Backend-Aware Virtual Sources
+
+By default a virtual definition is loaded eagerly: its sub-query runs
+once per query and all rows are held in memory. For large or remote
+backends, a **source provider** lets FlowQuery read only what a pattern
+needs. This is opt-in: existing `CREATE VIRTUAL` definitions behave
+exactly as before.
+
+The simplest way to write a provider is to subclass `NodeSource` or
+`RelationshipSource` and implement `scan(request, context)`. Implement
+`lookup` (nodes by id) or `expand` (relationships by `left_id`/`right_id`)
+when the backend can fetch selectively; the base class then declares the
+matching capability for you. `version` defaults to the current contract
+version, and capability keys may be written in snake_case
+(`max_batch_size`, `string_ordering`). A method may return a list of
+rows, an awaitable list, or an (async) iterable of pages.
+
+The `request` is a `SourceRequest`: a dict with the same camelCase keys
+as the TypeScript implementation (`request["pageSize"]`) that also
+accepts snake_case keys (`request["page_size"]`) and attribute access
+(`request.ids`, `request.side`, `request.predicate`, `request.page_size`).
+
+```python
+from flowquery import FlowQuery, NodeSource, RelationshipSource, cursor_pages
+
+class People(NodeSource):
+    capabilities = {
+        "cacheable": True,       # identical reads within one query may be cached
+        "max_batch_size": 50,    # ids per lookup/expand request
+        "predicates": {"operators": ["eq", "in", "gt", "gte", "lt", "lte"]},
+    }
+
+    def scan(self, request, context):
+        async def fetch(cursor):
+            page = await api.people(filter=request.predicate, cursor=cursor)
+            return {"rows": page.rows, "cursor": page.next_cursor}
+        return cursor_pages(fetch)
+
+    async def lookup(self, request, context):  # declares "lookup": True
+        return await api.people_by_ids(request.ids)
+
+class Knows(RelationshipSource):
+    async def scan(self, request, context):
+        return await api.all_knows()
+
+    async def expand(self, request, context):  # declares both expand sides
+        key = "from" if request.side == "left" else "to"
+        return await api.knows(**{key: request.ids})
+
+FlowQuery.register_node_source("Person", People())
+FlowQuery.register_relationship_source("KNOWS", "Person", "Person", Knows())
+
+fq = FlowQuery("MATCH (a:Person {id: 7})-[:KNOWS]->(b:Person) RETURN b.name LIMIT 10")
+await fq.run()
+print(fq.source_stats)  # calls, pages, rows, cacheHits, batches, plans...
+```
+
+Subclassing is optional: any object with a `capabilities` dict and a
+`scan` method works, and `SourceProvider` is a `typing.Protocol`
+describing that shape.
+
+The engine then loads correlated rows in batches instead of reading
+every person and relationship:
+
+- **Correlated loading and batching.** It issues id lookups, expands per
+  page of anchor nodes, and makes batched lookups for target nodes.
+- **Selective start points.** A chain may start from its more selective
+  end. The decision is recorded in `source_stats["plans"]`, and it can
+  change result order when there is no `ORDER BY`.
+- **Predicate push-down.** Pattern properties and `AND`-ed `WHERE`
+  comparisons (`=`, `<`, `<=`, `>`, `>=`, `IN`) against literals or
+  parameters are sent as `request["predicate"]`.
+- **Streaming with early stop under `LIMIT`.** Reading stops once the
+  limit is reached and the provider's iterator is closed.
+- **Query-scoped caching.**
+- **Cancellation.** Call `runner.cancel()` or pass
+  `SourceOptions(signal=...)` (an `asyncio.Event` or `SourceSignal`).
+  The query raises `QueryCancelledError`.
+- **Read contexts.** Optional `open_read_context()` and
+  `close_read_context(snapshot)` methods are called once per query.
+
+Providers may return a **superset**, because FlowQuery re-checks every
+row. `matches_predicate(predicate, row)` is a reference implementation
+of the predicate semantics.
+
+Errors are reported through typed exceptions:
+
+- `SourceCapabilityError`: an invalid declaration, raised at
+  registration.
+- `SourceResponseError`: malformed pages or a repeated cursor.
+- `SourceError`: any other provider failure.
+
+A provider may raise `SourceUnsupportedError` from `lookup`/`expand` to
+fall back to a scan.
+
+Query-level tuning goes in `RunnerOptions(sources=SourceOptions(...))`:
+`page_size` (256), `max_batch_size` (100), `cache_capacity` (10000),
+`max_prefetch_rows` (1024) and `reorder` (`True`).
+
+**In-memory sources.** `in_memory_node_source(rows)` and
+`in_memory_relationship_source(rows)` are ready-made providers over
+lists. They support lookup, expansion from both sides, every predicate
+operator and paging, which makes them handy for tests, examples and
+small reference data. Keyword options are `cacheable` (default `True`)
+and `max_batch_size`.
+
+```python
+from flowquery import in_memory_node_source, in_memory_relationship_source
+
+FlowQuery.register_node_source(
+    "Person", in_memory_node_source([{"id": 1, "name": "Ada"}, {"id": 2, "name": "Bob"}])
+)
+FlowQuery.register_relationship_source(
+    "KNOWS", "Person", "Person", in_memory_relationship_source([{"left_id": 1, "right_id": 2}])
+)
+```
+
+**Statement-backed sources.** A `CREATE VIRTUAL` definition can opt into
+the same contract declaratively with a `WITH CAPABILITIES { ... }` clause
+between the pattern and `AS`. Each request runs its sub-query with
+`$request` bound to the request (`operation`, `label`/`type`, `ids`,
+`side`, `predicate`, `pageSize`):
+
+```python
+await FlowQuery("""
+    CREATE VIRTUAL (:Ticket) WITH CAPABILITIES {lookup: true, streaming: true} AS {
+        LOAD JSON FROM f"https://api.example.com/tickets?ids={join(coalesce($request.ids, []), ',')}" AS t
+        RETURN t.id AS id, t.title AS title
+    }
+""").run()
+```
+
+The map takes the same (camelCase) keys as the capabilities dict;
+`version` defaults to the current contract version. Invalid capabilities
+reject the whole definition. Redefining the label without
+`WITH CAPABILITIES`, or deleting it, restores eager loading. The same
+opt-in is available programmatically with
+`FlowQuery.set_node_source_capabilities(label, capabilities)` and
+`FlowQuery.set_relationship_source_capabilities(...)`; pass `None` to
+opt out.
+
 ## Documentation
 
 - [Language Reference](https://github.com/microsoft/FlowQuery#language-reference) (clauses, expressions, functions, graph operations, and more)

{flowquery-1.0.65 → flowquery-1.0.66}/flowquery.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowquery
-Version: 1.0.65
+Version: 1.0.66
 Summary: A declarative query language for data processing pipelines
 Author-email: Team Microsoft FlowQuery <flowquery@microsoft.com>
 License: MIT
@@ -307,6 +307,147 @@ The same chain is reflected statically in `info.sources` so callers
 can introspect the upstream dependency graph without running the
 query.
 
+## Backend-Aware Virtual Sources
+
+By default a virtual definition is loaded eagerly: its sub-query runs
+once per query and all rows are held in memory. For large or remote
+backends, a **source provider** lets FlowQuery read only what a pattern
+needs. This is opt-in: existing `CREATE VIRTUAL` definitions behave
+exactly as before.
+
+The simplest way to write a provider is to subclass `NodeSource` or
+`RelationshipSource` and implement `scan(request, context)`. Implement
+`lookup` (nodes by id) or `expand` (relationships by `left_id`/`right_id`)
+when the backend can fetch selectively; the base class then declares the
+matching capability for you. `version` defaults to the current contract
+version, and capability keys may be written in snake_case
+(`max_batch_size`, `string_ordering`). A method may return a list of
+rows, an awaitable list, or an (async) iterable of pages.
+
+The `request` is a `SourceRequest`: a dict with the same camelCase keys
+as the TypeScript implementation (`request["pageSize"]`) that also
+accepts snake_case keys (`request["page_size"]`) and attribute access
+(`request.ids`, `request.side`, `request.predicate`, `request.page_size`).
+
+```python
+from flowquery import FlowQuery, NodeSource, RelationshipSource, cursor_pages
+
+class People(NodeSource):
+    capabilities = {
+        "cacheable": True,       # identical reads within one query may be cached
+        "max_batch_size": 50,    # ids per lookup/expand request
+        "predicates": {"operators": ["eq", "in", "gt", "gte", "lt", "lte"]},
+    }
+
+    def scan(self, request, context):
+        async def fetch(cursor):
+            page = await api.people(filter=request.predicate, cursor=cursor)
+            return {"rows": page.rows, "cursor": page.next_cursor}
+        return cursor_pages(fetch)
+
+    async def lookup(self, request, context):  # declares "lookup": True
+        return await api.people_by_ids(request.ids)
+
+class Knows(RelationshipSource):
+    async def scan(self, request, context):
+        return await api.all_knows()
+
+    async def expand(self, request, context):  # declares both expand sides
+        key = "from" if request.side == "left" else "to"
+        return await api.knows(**{key: request.ids})
+
+FlowQuery.register_node_source("Person", People())
+FlowQuery.register_relationship_source("KNOWS", "Person", "Person", Knows())
+
+fq = FlowQuery("MATCH (a:Person {id: 7})-[:KNOWS]->(b:Person) RETURN b.name LIMIT 10")
+await fq.run()
+print(fq.source_stats)  # calls, pages, rows, cacheHits, batches, plans...
+```
+
+Subclassing is optional: any object with a `capabilities` dict and a
+`scan` method works, and `SourceProvider` is a `typing.Protocol`
+describing that shape.
+
+The engine then loads correlated rows in batches instead of reading
+every person and relationship:
+
+- **Correlated loading and batching.** It issues id lookups, expands per
+  page of anchor nodes, and makes batched lookups for target nodes.
+- **Selective start points.** A chain may start from its more selective
+  end. The decision is recorded in `source_stats["plans"]`, and it can
+  change result order when there is no `ORDER BY`.
+- **Predicate push-down.** Pattern properties and `AND`-ed `WHERE`
+  comparisons (`=`, `<`, `<=`, `>`, `>=`, `IN`) against literals or
+  parameters are sent as `request["predicate"]`.
+- **Streaming with early stop under `LIMIT`.** Reading stops once the
+  limit is reached and the provider's iterator is closed.
+- **Query-scoped caching.**
+- **Cancellation.** Call `runner.cancel()` or pass
+  `SourceOptions(signal=...)` (an `asyncio.Event` or `SourceSignal`).
+  The query raises `QueryCancelledError`.
+- **Read contexts.** Optional `open_read_context()` and
+  `close_read_context(snapshot)` methods are called once per query.
+
+Providers may return a **superset**, because FlowQuery re-checks every
+row. `matches_predicate(predicate, row)` is a reference implementation
+of the predicate semantics.
+
+Errors are reported through typed exceptions:
+
+- `SourceCapabilityError`: an invalid declaration, raised at
+  registration.
+- `SourceResponseError`: malformed pages or a repeated cursor.
+- `SourceError`: any other provider failure.
+
+A provider may raise `SourceUnsupportedError` from `lookup`/`expand` to
+fall back to a scan.
+
+Query-level tuning goes in `RunnerOptions(sources=SourceOptions(...))`:
+`page_size` (256), `max_batch_size` (100), `cache_capacity` (10000),
+`max_prefetch_rows` (1024) and `reorder` (`True`).
+
+**In-memory sources.** `in_memory_node_source(rows)` and
+`in_memory_relationship_source(rows)` are ready-made providers over
+lists. They support lookup, expansion from both sides, every predicate
+operator and paging, which makes them handy for tests, examples and
+small reference data. Keyword options are `cacheable` (default `True`)
+and `max_batch_size`.
+
+```python
+from flowquery import in_memory_node_source, in_memory_relationship_source
+
+FlowQuery.register_node_source(
+    "Person", in_memory_node_source([{"id": 1, "name": "Ada"}, {"id": 2, "name": "Bob"}])
+)
+FlowQuery.register_relationship_source(
+    "KNOWS", "Person", "Person", in_memory_relationship_source([{"left_id": 1, "right_id": 2}])
+)
+```
+
+**Statement-backed sources.** A `CREATE VIRTUAL` definition can opt into
+the same contract declaratively with a `WITH CAPABILITIES { ... }` clause
+between the pattern and `AS`. Each request runs its sub-query with
+`$request` bound to the request (`operation`, `label`/`type`, `ids`,
+`side`, `predicate`, `pageSize`):
+
+```python
+await FlowQuery("""
+    CREATE VIRTUAL (:Ticket) WITH CAPABILITIES {lookup: true, streaming: true} AS {
+        LOAD JSON FROM f"https://api.example.com/tickets?ids={join(coalesce($request.ids, []), ',')}" AS t
+        RETURN t.id AS id, t.title AS title
+    }
+""").run()
+```
+
+The map takes the same (camelCase) keys as the capabilities dict;
+`version` defaults to the current contract version. Invalid capabilities
+reject the whole definition. Redefining the label without
+`WITH CAPABILITIES`, or deleting it, restores eager loading. The same
+opt-in is available programmatically with
+`FlowQuery.set_node_source_capabilities(label, capabilities)` and
+`FlowQuery.set_relationship_source_capabilities(...)`; pass `None` to
+opt out.
+
 ## Documentation
 
 - [Language Reference](https://github.com/microsoft/FlowQuery#language-reference) (clauses, expressions, functions, graph operations, and more)

{flowquery-1.0.65 → flowquery-1.0.66}/flowquery.egg-info/SOURCES.txt

@@ -32,7 +32,12 @@ src/graph/relationship.py
 src/graph/relationship_data.py
 src/graph/relationship_match_collector.py
 src/graph/relationship_reference.py
+src/graph/source_access.py
+src/graph/source_context.py
+src/graph/source_provider.py
+src/graph/statement_source.py
 src/graph/virtual_sources.py
+src/graph/virtual_statement.py
 src/io/__init__.py
 src/io/command_line.py
 src/parsing/__init__.py

{flowquery-1.0.65 → flowquery-1.0.66}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flowquery"
-version = "1.0.65"
+version = "1.0.66"
 description = "A declarative query language for data processing pipelines"
 readme = "README.md"
 requires-python = ">=3.10"

{flowquery-1.0.65 → flowquery-1.0.66}/src/__init__.py

@@ -24,6 +24,27 @@ from .compute.runner import (
     RunnerMetadata,
     RunnerOptions,
 )
+from .graph.source_context import SourceOptions
+from .graph.source_provider import (
+    PREDICATE_OPERATORS,
+    SOURCE_CONTRACT_VERSION,
+    NodeSource,
+    QueryCancelledError,
+    RelationshipSource,
+    SourceCapabilityError,
+    SourceError,
+    SourceProvider,
+    SourceReadContext,
+    SourceRequest,
+    SourceResponseError,
+    SourceResult,
+    SourceSignal,
+    SourceUnsupportedError,
+    cursor_pages,
+    in_memory_node_source,
+    in_memory_relationship_source,
+    matches_predicate,
+)
 from .io.command_line import CommandLine
 from .parsing.functions.aggregate_function import AggregateFunction
 from .parsing.functions.async_function import AsyncFunction
@@ -80,5 +101,24 @@ __all__ = [
     "FunctionDef",
     "FunctionMetadata",
     "FunctionCategory",
+    "SOURCE_CONTRACT_VERSION",
+    "PREDICATE_OPERATORS",
+    "SourceOptions",
+    "SourceSignal",
+    "SourceReadContext",
+    "SourceError",
+    "SourceCapabilityError",
+    "SourceResponseError",
+    "SourceUnsupportedError",
+    "QueryCancelledError",
+    "SourceProvider",
+    "SourceRequest",
+    "SourceResult",
+    "NodeSource",
+    "RelationshipSource",
+    "cursor_pages",
+    "matches_predicate",
+    "in_memory_node_source",
+    "in_memory_relationship_source",
 ]
 

{flowquery-1.0.65 → flowquery-1.0.66}/src/compute/flowquery.py

@@ -4,7 +4,7 @@ Extends Runner with extensibility features such as function listing
 and plugin registration, keeping the Runner focused on execution.
 """
 
-from typing import List, Optional, Type
+from typing import Any, Dict, List, Optional, Type
 
 from ..parsing.functions.function import Function
 from ..parsing.functions.function_factory import FunctionFactory
@@ -66,3 +66,53 @@ class FlowQuery(Runner):
             Function metadata or None
         """
         return get_function_metadata(name.lower())
+
+    @staticmethod
+    def register_node_source(label: str, provider: Any) -> None:
+        """Register a backend-aware node source for ``label``.
+
+        Replaces any existing virtual definition for the label.  The provider
+        exposes ``capabilities`` and ``scan`` (and optionally ``lookup``).
+        """
+        from ..graph.database import Database
+
+        Database.get_instance().register_node_source(label, provider)
+
+    @staticmethod
+    def register_relationship_source(
+        rel_type: str,
+        source_label: Optional[str],
+        target_label: Optional[str],
+        provider: Any,
+    ) -> None:
+        """Register a backend-aware relationship source for
+        ``(:source_label)-[:rel_type]->(:target_label)``."""
+        from ..graph.database import Database
+
+        Database.get_instance().register_relationship_source(
+            rel_type, source_label, target_label, provider
+        )
+
+    @staticmethod
+    def set_node_source_capabilities(
+        label: str, capabilities: Optional[Dict[str, Any]]
+    ) -> None:
+        """Opt a ``CREATE VIRTUAL (:label) AS { ... }`` definition into the
+        source contract with explicit capabilities, or pass ``None`` to opt out."""
+        from ..graph.database import Database
+
+        Database.get_instance().set_node_source_capabilities(label, capabilities)
+
+    @staticmethod
+    def set_relationship_source_capabilities(
+        rel_type: str,
+        source_label: Optional[str],
+        target_label: Optional[str],
+        capabilities: Optional[Dict[str, Any]],
+    ) -> None:
+        """Relationship counterpart of :meth:`set_node_source_capabilities`."""
+        from ..graph.database import Database
+
+        Database.get_instance().set_relationship_source_capabilities(
+            rel_type, source_label, target_label, capabilities
+        )