gestaltdb 0.3.0__tar.gz

gestaltdb-0.3.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: gestaltdb
+Version: 0.3.0
+Summary: A pure Python GraphDB for attributed graphs.
+Requires-Python: <3.14,>=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: google>=3.0.0
+Requires-Dist: msgpack>=1.1.2
+Requires-Dist: plyvel>=1.5.1
+Requires-Dist: protobuf>=6.33.6
+Provides-Extra: lmdb
+Requires-Dist: lmdb; extra == "lmdb"
+Provides-Extra: leveldb
+Requires-Dist: plyvel; extra == "leveldb"
+Provides-Extra: msgpack
+Requires-Dist: msgpack; extra == "msgpack"
+Provides-Extra: protobuf
+Requires-Dist: protobuf; extra == "protobuf"
+Provides-Extra: bloom
+Requires-Dist: pybloom-live; extra == "bloom"
+Provides-Extra: coverage
+Requires-Dist: coverage; extra == "coverage"
+Requires-Dist: pytest; extra == "coverage"
+Provides-Extra: docs
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Provides-Extra: rocksdb
+Requires-Dist: pyrex-rocksdb>=0.3.0a0; extra == "rocksdb"
+Provides-Extra: arrow
+Requires-Dist: pyarrow; extra == "arrow"
+Provides-Extra: polars
+Requires-Dist: polars; extra == "polars"
+Requires-Dist: pyarrow; extra == "polars"
+Provides-Extra: fast-ingest
+Requires-Dist: pyarrow; extra == "fast-ingest"
+Requires-Dist: polars; extra == "fast-ingest"
+Requires-Dist: pyrex-rocksdb>=0.3.0a0; extra == "fast-ingest"
+Provides-Extra: all
+Requires-Dist: lmdb; extra == "all"
+Requires-Dist: msgpack; extra == "all"
+Requires-Dist: plyvel; extra == "all"
+Requires-Dist: protobuf; extra == "all"
+Requires-Dist: pybloom-live; extra == "all"
+Requires-Dist: pyrex-rocksdb>=0.3.0a0; extra == "all"
+Requires-Dist: pyarrow; extra == "all"
+Requires-Dist: polars; extra == "all"
+Provides-Extra: dev
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: furo; extra == "dev"
+Requires-Dist: lmdb; extra == "dev"
+Requires-Dist: msgpack; extra == "dev"
+Requires-Dist: myst-parser; extra == "dev"
+Requires-Dist: plyvel; extra == "dev"
+Requires-Dist: protobuf; extra == "dev"
+Requires-Dist: pybloom-live; extra == "dev"
+Requires-Dist: pyrex-rocksdb>=0.3.0a0; extra == "dev"
+Requires-Dist: pyarrow; extra == "dev"
+Requires-Dist: polars; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+
+# GestaltDB
+
+![Coverage](https://raw.githubusercontent.com/mylonasc/gestaltdb/refs/heads/main/assets/coverage_badge.svg)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://mylonasc.github.io/gestaltdb/)
+
+GestaltDB is a pure Python graph database toolkit for attributed graphs. It stores nodes, edges, labels, typed adjacency records, and property indexes on embedded key-value backends.
+
+Documentation: https://mylonasc.github.io/gestaltdb/
+
+## Install From PyPI
+
+With pip:
+
+```sh
+python -m pip install gestaltdb
+```
+
+With uv:
+
+```sh
+uv add gestaltdb
+```
+
+Install columnar ingestion dependencies:
+
+```sh
+python -m pip install "gestaltdb[arrow,polars]"
+```
+
+Install all optional backends and serializers:
+
+```sh
+python -m pip install "gestaltdb[all]"
+```
+
+Optional extras include `lmdb`, `leveldb`, `rocksdb`, `arrow`, `polars`, `fast-ingest`, `msgpack`, `protobuf`, `bloom`, `docs`, `dev`, and `all`.
+
+## Basic Example
+
+```python
+from tempfile import TemporaryDirectory
+
+from gestaltdb.graphdb import Edge, GraphDB, Node
+from gestaltdb.kvstores import LevelDBStore
+from gestaltdb.serializers import PickleSerializer
+
+with TemporaryDirectory() as tmpdir:
+    graph = GraphDB(LevelDBStore(path=f"{tmpdir}/graph"), PickleSerializer())
+
+    graph.put_node(Node(node_id="alice", labels=["Person"], properties={"name": "Alice"}))
+    graph.put_node(Node(node_id="bob", labels=["Person"], properties={"name": "Bob"}))
+    graph.put_edge(Edge(
+        edge_id="alice-knows-bob",
+        source="alice",
+        target="bob",
+        properties={"type": "knows", "since": 2024},
+    ))
+
+    result = graph.query('MATCH (a:Person {name: "Alice"}) MATCH (a)-[:knows]->(b) RETURN a.id, b.name')
+    print(result.records)
+
+    graph.close()
+```
+
+## Arrow Ingestion Example
+
+This example ingests entity columns from PyArrow arrays. `JSONSerializer` lets GestaltDB build node and edge payloads from structured columns.
+
+```python
+from tempfile import TemporaryDirectory
+
+import pyarrow as pa
+
+from gestaltdb.graphdb import GraphDB
+from gestaltdb.kvstores import LevelDBStore
+from gestaltdb.serializers import JSONSerializer
+
+with TemporaryDirectory() as tmpdir:
+    graph = GraphDB(LevelDBStore(path=f"{tmpdir}/graph"), JSONSerializer())
+
+    graph.ingest_nodes_arrow_entities(
+        pa.array(["alice", "bob", "carol"]),
+        labels=pa.array([["Person"], ["Person"], ["Person"]]),
+        properties={
+            "name": pa.array(["Alice", "Bob", "Carol"]),
+            "age": pa.array([34, 36, 29]),
+        },
+    )
+
+    graph.ingest_edges_arrow_entities(
+        pa.array(["alice-knows-bob", "bob-knows-carol"]),
+        pa.array(["alice", "bob"]),
+        pa.array(["bob", "carol"]),
+        pa.array(["knows", "knows"]),
+        properties={"since": pa.array([2024, 2025])},
+    )
+
+    result = graph.query('MATCH (a:Person {name: "Alice"}) MATCH (a)-[:knows]->(b) RETURN a.id, b.name')
+    print(result.records)
+
+    graph.close()
+```
+
+## Polars Ingestion Example
+
+This example ingests the same graph from Polars DataFrames. Property columns are converted into node and edge payloads during ingestion.
+
+```python
+from tempfile import TemporaryDirectory
+
+import polars as pl
+
+from gestaltdb.graphdb import GraphDB
+from gestaltdb.kvstores import LevelDBStore
+from gestaltdb.serializers import JSONSerializer
+
+nodes = pl.DataFrame({
+    "node_id": ["alice", "bob", "carol"],
+    "labels": [["Person"], ["Person"], ["Person"]],
+    "name": ["Alice", "Bob", "Carol"],
+    "age": [34, 36, 29],
+})
+
+edges = pl.DataFrame({
+    "edge_id": ["alice-knows-bob", "bob-knows-carol"],
+    "source": ["alice", "bob"],
+    "target": ["bob", "carol"],
+    "edge_type": ["knows", "knows"],
+    "since": [2024, 2025],
+})
+
+with TemporaryDirectory() as tmpdir:
+    graph = GraphDB(LevelDBStore(path=f"{tmpdir}/graph"), JSONSerializer())
+
+    graph.ingest_nodes_polars_entities(nodes)
+    graph.ingest_edges_polars_entities(edges)
+
+    result = graph.query('MATCH (a:Person) MATCH (a)-[:knows]->(b) RETURN a.name, b.name ORDER BY a.name')
+    print(result.records)
+
+    graph.close()
+```
+
+## Install From A Checkout
+
+From a local checkout:
+
+```sh
+uv sync
+```
+
+Install into another project:
+
+```sh
+uv add /path/to/gestaltdb
+```
+
+With pip:
+
+```sh
+python -m pip install /path/to/gestaltdb
+```
+
+## Features
+
+- Attributed `Node` and `Edge` objects with stable IDs.
+- Native node labels and typed edge traversal through `edge.properties["type"]`.
+- LMDB, LevelDB, and RocksDB/PyRex storage backends.
+- Pickle, JSON, MessagePack, and Protobuf serializers.
+- Label, relationship type, property, composite, and range indexes.
+- Read-only Cypher subset for indexed scans, typed traversal, filtering, ordering, limits, and chained `MATCH` clauses.
+- Bulk and columnar ingestion helpers for Arrow and Polars.
+- Typed path and subgraph sampling.
+
+See the full documentation for backend selection, indexing, Cypher syntax, ingestion, sampling, and benchmarks.
+
+<details>
+<summary>Name origin</summary>
+
+The name GestaltDB is inspired by Gestalt psychology and the idea that the whole is something more than its parts.
+
+</details>

gestaltdb-0.3.0/README.md

@@ -0,0 +1,182 @@
+# GestaltDB
+
+![Coverage](https://raw.githubusercontent.com/mylonasc/gestaltdb/refs/heads/main/assets/coverage_badge.svg)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://mylonasc.github.io/gestaltdb/)
+
+GestaltDB is a pure Python graph database toolkit for attributed graphs. It stores nodes, edges, labels, typed adjacency records, and property indexes on embedded key-value backends.
+
+Documentation: https://mylonasc.github.io/gestaltdb/
+
+## Install From PyPI
+
+With pip:
+
+```sh
+python -m pip install gestaltdb
+```
+
+With uv:
+
+```sh
+uv add gestaltdb
+```
+
+Install columnar ingestion dependencies:
+
+```sh
+python -m pip install "gestaltdb[arrow,polars]"
+```
+
+Install all optional backends and serializers:
+
+```sh
+python -m pip install "gestaltdb[all]"
+```
+
+Optional extras include `lmdb`, `leveldb`, `rocksdb`, `arrow`, `polars`, `fast-ingest`, `msgpack`, `protobuf`, `bloom`, `docs`, `dev`, and `all`.
+
+## Basic Example
+
+```python
+from tempfile import TemporaryDirectory
+
+from gestaltdb.graphdb import Edge, GraphDB, Node
+from gestaltdb.kvstores import LevelDBStore
+from gestaltdb.serializers import PickleSerializer
+
+with TemporaryDirectory() as tmpdir:
+    graph = GraphDB(LevelDBStore(path=f"{tmpdir}/graph"), PickleSerializer())
+
+    graph.put_node(Node(node_id="alice", labels=["Person"], properties={"name": "Alice"}))
+    graph.put_node(Node(node_id="bob", labels=["Person"], properties={"name": "Bob"}))
+    graph.put_edge(Edge(
+        edge_id="alice-knows-bob",
+        source="alice",
+        target="bob",
+        properties={"type": "knows", "since": 2024},
+    ))
+
+    result = graph.query('MATCH (a:Person {name: "Alice"}) MATCH (a)-[:knows]->(b) RETURN a.id, b.name')
+    print(result.records)
+
+    graph.close()
+```
+
+## Arrow Ingestion Example
+
+This example ingests entity columns from PyArrow arrays. `JSONSerializer` lets GestaltDB build node and edge payloads from structured columns.
+
+```python
+from tempfile import TemporaryDirectory
+
+import pyarrow as pa
+
+from gestaltdb.graphdb import GraphDB
+from gestaltdb.kvstores import LevelDBStore
+from gestaltdb.serializers import JSONSerializer
+
+with TemporaryDirectory() as tmpdir:
+    graph = GraphDB(LevelDBStore(path=f"{tmpdir}/graph"), JSONSerializer())
+
+    graph.ingest_nodes_arrow_entities(
+        pa.array(["alice", "bob", "carol"]),
+        labels=pa.array([["Person"], ["Person"], ["Person"]]),
+        properties={
+            "name": pa.array(["Alice", "Bob", "Carol"]),
+            "age": pa.array([34, 36, 29]),
+        },
+    )
+
+    graph.ingest_edges_arrow_entities(
+        pa.array(["alice-knows-bob", "bob-knows-carol"]),
+        pa.array(["alice", "bob"]),
+        pa.array(["bob", "carol"]),
+        pa.array(["knows", "knows"]),
+        properties={"since": pa.array([2024, 2025])},
+    )
+
+    result = graph.query('MATCH (a:Person {name: "Alice"}) MATCH (a)-[:knows]->(b) RETURN a.id, b.name')
+    print(result.records)
+
+    graph.close()
+```
+
+## Polars Ingestion Example
+
+This example ingests the same graph from Polars DataFrames. Property columns are converted into node and edge payloads during ingestion.
+
+```python
+from tempfile import TemporaryDirectory
+
+import polars as pl
+
+from gestaltdb.graphdb import GraphDB
+from gestaltdb.kvstores import LevelDBStore
+from gestaltdb.serializers import JSONSerializer
+
+nodes = pl.DataFrame({
+    "node_id": ["alice", "bob", "carol"],
+    "labels": [["Person"], ["Person"], ["Person"]],
+    "name": ["Alice", "Bob", "Carol"],
+    "age": [34, 36, 29],
+})
+
+edges = pl.DataFrame({
+    "edge_id": ["alice-knows-bob", "bob-knows-carol"],
+    "source": ["alice", "bob"],
+    "target": ["bob", "carol"],
+    "edge_type": ["knows", "knows"],
+    "since": [2024, 2025],
+})
+
+with TemporaryDirectory() as tmpdir:
+    graph = GraphDB(LevelDBStore(path=f"{tmpdir}/graph"), JSONSerializer())
+
+    graph.ingest_nodes_polars_entities(nodes)
+    graph.ingest_edges_polars_entities(edges)
+
+    result = graph.query('MATCH (a:Person) MATCH (a)-[:knows]->(b) RETURN a.name, b.name ORDER BY a.name')
+    print(result.records)
+
+    graph.close()
+```
+
+## Install From A Checkout
+
+From a local checkout:
+
+```sh
+uv sync
+```
+
+Install into another project:
+
+```sh
+uv add /path/to/gestaltdb
+```
+
+With pip:
+
+```sh
+python -m pip install /path/to/gestaltdb
+```
+
+## Features
+
+- Attributed `Node` and `Edge` objects with stable IDs.
+- Native node labels and typed edge traversal through `edge.properties["type"]`.
+- LMDB, LevelDB, and RocksDB/PyRex storage backends.
+- Pickle, JSON, MessagePack, and Protobuf serializers.
+- Label, relationship type, property, composite, and range indexes.
+- Read-only Cypher subset for indexed scans, typed traversal, filtering, ordering, limits, and chained `MATCH` clauses.
+- Bulk and columnar ingestion helpers for Arrow and Polars.
+- Typed path and subgraph sampling.
+
+See the full documentation for backend selection, indexing, Cypher syntax, ingestion, sampling, and benchmarks.
+
+<details>
+<summary>Name origin</summary>
+
+The name GestaltDB is inspired by Gestalt psychology and the idea that the whole is something more than its parts.
+
+</details>

gestaltdb-0.3.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gestaltdb"
+version = "0.3.0"
+description = "A pure Python GraphDB for attributed graphs."
+readme = "README.md"
+requires-python = ">=3.9,<3.14"
+dependencies = [
+    "google>=3.0.0",
+    "msgpack>=1.1.2",
+    "plyvel>=1.5.1",
+    "protobuf>=6.33.6",
+]
+
+[project.optional-dependencies]
+lmdb = ["lmdb"]
+leveldb = ["plyvel"]
+msgpack = ["msgpack"]
+protobuf = ["protobuf"]
+bloom = ["pybloom-live"]
+coverage = ["coverage", "pytest"]
+docs = ["furo", "myst-parser", "sphinx"]
+rocksdb = ["pyrex-rocksdb>=0.3.0a0"]
+arrow = ["pyarrow"]
+polars = ["polars", "pyarrow"]
+fast-ingest = ["pyarrow", "polars", "pyrex-rocksdb>=0.3.0a0"]
+all = ["lmdb", "msgpack", "plyvel", "protobuf", "pybloom-live", "pyrex-rocksdb>=0.3.0a0", "pyarrow", "polars"]
+dev = ["coverage", "furo", "lmdb", "msgpack", "myst-parser", "plyvel", "protobuf", "pybloom-live", "pyrex-rocksdb>=0.3.0a0", "pyarrow", "polars", "pytest", "sphinx"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "coverage>=7.10.7",
+    "pytest>=8.0",
+]

gestaltdb-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gestaltdb-0.3.0/src/gestaltdb/__init__.py

@@ -0,0 +1,7 @@
+"""GestaltDB package."""
+
+from .sampling import SamplingHop, SamplingPattern
+from .ingestion import EdgeList, NodeList
+from .cypher import QueryResult
+
+__all__ = ["EdgeList", "NodeList", "QueryResult", "SamplingHop", "SamplingPattern"]

gestaltdb-0.3.0/src/gestaltdb/cypher.py

@@ -0,0 +1,104 @@
+"""Minimal read-only Cypher support for GestaltDB.
+
+The supported subset maps directly to existing typed adjacency and sampling APIs:
+
+    MATCH (a {id: "node-id"})-[:TYPE1]->(b)<-[:TYPE2]-(c) RETURN a.name, b LIMIT 10
+    CALL pg.sample_typed_paths(["node-id"], [{"edge_type": "TYPE", "sample_size": 2}]) YIELD path RETURN path
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .cypher_ast import MatchQuery, MultiMatchQuery, NodeScanQuery, RelationshipScanQuery, SampleTypedPathsCall
+from .cypher_plan import LogicalPlan, plan_query
+from .cypher_parser import parse as _parse_query, split_top_level_args as _split_top_level_args
+from .cypher_runtime import QueryContext, execute_match, execute_multi_match, execute_node_scan, execute_relationship_scan
+
+
+@dataclass(frozen=True)
+class QueryResult:
+    """Tabular query result returned by ``GraphDB.query``.
+
+    ``columns`` contains projected column names in return order. ``records`` is
+    a list of dictionaries keyed by column name.
+
+    Examples:
+        >>> result = QueryResult(columns=("n",), records=[{"n": "node"}])
+        >>> len(result)
+        1
+        >>> list(result)[0]["n"]
+        'node'
+    """
+
+    columns: tuple[str, ...]
+    records: list[dict[str, object]]
+
+    def __iter__(self):
+        """Iterate over result records."""
+        return iter(self.records)
+
+    def __len__(self):
+        """Return the number of result records."""
+        return len(self.records)
+
+
+def parse(query: str) -> MatchQuery | SampleTypedPathsCall | NodeScanQuery | RelationshipScanQuery | MultiMatchQuery:
+    """Parse the supported Cypher subset.
+
+    Args:
+        query: Cypher query text.
+
+    Returns:
+        Parsed query object.
+
+    Raises:
+        ValueError: If the query is outside the supported subset.
+
+    Examples:
+        >>> parse('MATCH (n:Drug) RETURN n').label
+        'Drug'
+    """
+    return _parse_query(query)
+
+
+def plan(query: str) -> LogicalPlan:
+    """Return the logical plan for a supported Cypher query."""
+    return plan_query(parse(query))
+
+
+def execute(graph, query: str, parameters: dict[str, object] | None = None) -> QueryResult:
+    """Execute a supported Cypher query against a ``GraphDB`` instance.
+
+    Args:
+        graph: ``GraphDB`` instance used for indexed lookups and traversal.
+        query: Cypher query text.
+
+    Returns:
+        ``QueryResult`` with projected records.
+
+    Examples:
+        >>> execute(graph_db, 'MATCH (n:Drug) RETURN n')  # doctest: +SKIP
+    """
+    parsed = parse(query)
+    plan_query(parsed)
+    parameters = parameters or {}
+    if isinstance(parsed, SampleTypedPathsCall):
+        paths = graph.sample_typed_paths(parsed.seed_ids, parsed.pattern)
+        if parsed.limit is not None:
+            paths = paths[:parsed.limit]
+        return QueryResult(
+            columns=parsed.returns,
+            records=[{"path": path} for path in paths],
+        )
+    if isinstance(parsed, NodeScanQuery):
+        records = execute_node_scan(parsed, QueryContext(graph=graph, parameters=parameters))
+        return QueryResult(columns=parsed.returns, records=records)
+    if isinstance(parsed, RelationshipScanQuery):
+        records = execute_relationship_scan(parsed, QueryContext(graph=graph, parameters=parameters))
+        return QueryResult(columns=parsed.returns, records=records)
+    if isinstance(parsed, MultiMatchQuery):
+        records = execute_multi_match(parsed, QueryContext(graph=graph, parameters=parameters))
+        return QueryResult(columns=parsed.returns, records=records)
+    records = execute_match(parsed, QueryContext(graph=graph, parameters=parameters))
+    return QueryResult(columns=parsed.returns, records=records)