{"id":36711148,"url":"https://github.com/lance-format/lance-graph","last_synced_at":"2026-02-15T07:16:33.406Z","repository":{"id":317736332,"uuid":"1066706544","full_name":"lance-format/lance-graph","owner":"lance-format","description":"Run Graph Queries with Lance","archived":false,"fork":false,"pushed_at":"2026-02-08T21:26:22.000Z","size":1303,"stargazers_count":98,"open_issues_count":18,"forks_count":17,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-02-08T23:57:19.781Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lance-format.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-29T21:08:13.000Z","updated_at":"2026-02-08T21:26:25.000Z","dependencies_parsed_at":"2025-10-02T19:21:34.725Z","dependency_job_id":"3d825275-fc18-4029-9fa5-41513fe7720d","html_url":"https://github.com/lance-format/lance-graph","commit_stats":null,"previous_names":["lancedb/lance-graph","lance-format/lance-graph"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/lance-format/lance-graph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lance-format%2Flance-graph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lance-format%2Flance-graph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lance-format%2Flance-graph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lance-format%2Flance-graph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lance-format","download_url":"https://codeload.github.com/lance-format/lance-graph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lance-format%2Flance-graph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29471160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T05:26:30.465Z","status":"ssl_error","status_checked_at":"2026-02-15T05:26:21.858Z","response_time":118,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-12T11:48:02.265Z","updated_at":"2026-02-15T07:16:33.401Z","avatar_url":"https://github.com/lance-format.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lance Graph\n\nLance Graph is a Cypher-capable graph query engine built in Rust with Python bindings for building high-performance, scalable, and serverless multimodal knowledge graphs.\n\nThis repository contains:\n\n- `crates/lance-graph` – the Cypher-capable query engine implemented in Rust\n- `python/` – PyO3 bindings and Python packages:\n  - `lance_graph` – thin wrapper around the Rust query engine\n  - `knowledge_graph` – Lance-backed knowledge graph CLI, API, and utilities\n\nSee `docs/project_structure.md` for the proposed workspace-based structure from\nissue #92.\n\n## Prerequisites\n\n- Rust toolchain (1.82 or newer recommended)\n- Python 3.11\n- [`uv`](https://docs.astral.sh/uv/) available on your `PATH`\n\n## Rust crate quick start\n\n```bash\ncd crates/lance-graph\ncargo check\ncargo test\n```\n\n## Python package quick start\n\n```bash\ncd python\nuv venv --python 3.11 .venv      # create the local virtualenv\nsource .venv/bin/activate         # activate the virtual environment\nuv pip install 'maturin[patchelf]' # install build tool\nuv pip install -e '.[tests]'     # editable install with test extras\nmaturin develop                   # build and install the Rust extension\npytest python/tests/ -v          # run the test suite\n```\n\n\u003e If another virtual environment is already active, run `deactivate` (or\n\u003e `unset VIRTUAL_ENV`) before the `uv run` command so uv binds to `.venv`.\n\n## Python example: Cypher query\n\n```python\nimport pyarrow as pa\nfrom lance_graph import CypherQuery, GraphConfig\n\npeople = pa.table({\n    \"person_id\": [1, 2, 3, 4],\n    \"name\": [\"Alice\", \"Bob\", \"Carol\", \"David\"],\n    \"age\": [28, 34, 29, 42],\n})\n\nconfig = (\n    GraphConfig.builder()\n    .with_node_label(\"Person\", \"person_id\")\n    .build()\n)\n\nquery = (\n    CypherQuery(\"MATCH (p:Person) WHERE p.age \u003e 30 RETURN p.name AS name, p.age AS age\")\n    .with_config(config)\n)\nresult = query.execute({\"Person\": people})\nprint(result.to_pydict())  # {'name': ['Bob', 'David'], 'age': [34, 42]}\n```\n\n## Knowledge Graph CLI \u0026 API\n\nThe `knowledge_graph` package layers a simple Lance-backed knowledge graph\nservice on top of the `lance_graph` engine. It provides:\n\n- A CLI (`knowledge_graph.main`) for initializing storage, running Cypher\n  queries, and bootstrapping data via heuristic text extraction.\n- A reusable FastAPI component, plus a standalone web service\n  (`knowledge_graph.webservice`) that exposes query and dataset endpoints.\n- Storage helpers that persist node and relationship tables as Lance datasets.\n\n### CLI usage\n\n```bash\nuv run knowledge_graph --init                    # initialize storage and schema stub\nuv run knowledge_graph --list-datasets           # list Lance datasets on disk\nuv run knowledge_graph --extract-preview notes.txt\nuv run knowledge_graph --extract-preview \"Alice joined the graph team\"\nuv run knowledge_graph --extract-and-add notes.txt\nuv run knowledge_graph \"MATCH (n) RETURN n LIMIT 5\"\nuv run knowledge_graph --log-level DEBUG --extract-preview \"Inline text\"\nuv run knowledge_graph --ask \"Who is working on the Presto project?\"\n\n\n# Configure LLM extraction (default)\nuv sync --extra llm  # install optional LLM dependencies\nuv sync --extra lance-storage  # install Lance dataset support\nexport OPENAI_API_KEY=sk-...\nuv run knowledge_graph --llm-model gpt-4o-mini --extract-preview notes.txt\n\n# Supply additional OpenAI client options via YAML (base_url, headers, etc.)\nuv run knowledge_graph --llm-config llm_config.yaml --extract-and-add notes.txt\n\n# Fall back to the heuristic extractor when LLM access is unavailable\nuv run knowledge_graph --extractor heuristic --extract-preview notes.txt\n\n```\n\nThe default extractor uses OpenAI. Configure credentials via environment\nvariables supported by the SDK (for example `OPENAI_API_BASE` or\n`OPENAI_API_KEY`), or place them in a YAML file passed through `--llm-config`.\nOverride the model and temperature with `--llm-model` and `--llm-temperature`.\n```\n\nBy default the CLI writes datasets under `./knowledge_graph_data`. Provide\n`--root` and `--schema` to point at alternate storage locations and schema YAML.\n\n### FastAPI service\n\nRun the web service after installing the `knowledge_graph` package (and\ndependencies such as FastAPI):\n\n```bash\nuv run --package knowledge_graph knowledge_graph-webservice\n```\n\nThe service exposes endpoints under `/graph`, including `/graph/health`,\n`/graph/query`, `/graph/datasets`, and `/graph/schema`.\n\n### Development workflow\n\nFor linting and type checks:\n\n```bash\n# Install dev dependencies and run linters\nuv pip install -e '.[dev]'\nruff format python/              # format code\nruff check python/               # lint code\npyright                          # type check\n\n# Or run individual tests\npytest python/tests/test_graph.py::test_basic_node_selection -v\n```\n\nThe Python README (`python/README.md`) contains additional details if you are\nworking solely on the bindings.\n\n## Benchmarks\n\n- Requirements:\n  - protoc: install `protobuf-compiler` (Debian/Ubuntu: `sudo apt-get install -y protobuf-compiler`).\n  - Optional: gnuplot for Criterion's gnuplot backend; otherwise the plotters backend is used.\n\n- Run (from `crates/lance-graph`):\n\n```bash\ncargo bench --bench graph_execution\n\n# Quicker local run (shorter warm-up/measurement):\ncargo bench --bench graph_execution -- --warm-up-time 1 --measurement-time 2 --sample-size 10\n```\n\n- Reports:\n  - Global index: `crates/lance-graph/target/criterion/report/index.html`\n  - Group index: `crates/lance-graph/target/criterion/cypher_execution/report/index.html`\n\n- Typical results (x86_64, quick run: warm-up 1s, measurement 2s, sample size 10):\n\n| Benchmark                | Size      | Median time | Approx. throughput |\n|--------------------------|-----------|-------------|--------------------|\n| basic_node_filter        | 100       | ~680 µs     | ~147 Kelem/s       |\n| basic_node_filter        | 10,000    | ~715 µs     | ~13.98 Melem/s     |\n| basic_node_filter        | 1,000,000 | ~743 µs     | ~1.35 Gelem/s      |\n| single_hop_expand        | 100       | ~2.79 ms    | ~35.9 Kelem/s      |\n| single_hop_expand        | 10,000    | ~3.77 ms    | ~2.65 Melem/s      |\n| single_hop_expand        | 1,000,000 | ~3.70 ms    | ~270 Melem/s       |\n| two_hop_expand           | 100       | ~4.52 ms    | ~22.1 Kelem/s      |\n| two_hop_expand           | 10,000    | ~6.41 ms    | ~1.56 Melem/s      |\n| two_hop_expand           | 1,000,000 | ~6.16 ms    | ~162 Melem/s       |\n\nNumbers are illustrative; your hardware, compiler, and runtime load will affect results.\n\n## External Wiki\n\nFor additional documentation, architecture, and examples, see the DeepWiki page: [DeepWiki — lance-graph](https://deepwiki.com/lancedb/lance-graph)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flance-format%2Flance-graph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flance-format%2Flance-graph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flance-format%2Flance-graph/lists"}