Skip to content

Commit 3f808f8

Browse files
badmonster0badmonster0
authored
docs(kuzu): update docs and examples to cover more for Kuzu (#583)
1 parent 5f9edcc commit 3f808f8

File tree

5 files changed

+116
-87
lines changed

5 files changed

+116
-87
lines changed

‎docs/docs/ops/storages.md‎

Lines changed: 44 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -386,19 +386,7 @@ You can find end-to-end examples fitting into any of supported property graphs i
386386

387387
### Neo4j
388388

389-
If you don't have a Neo4j database, you can start a Neo4j database using our docker compose config:
390-
391-
```bash
392-
docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex/refs/heads/main/dev/neo4j.yaml) up -d
393-
```
394-
395-
:::warning
396-
397-
The docker compose config above will start a Neo4j Enterprise instance under the [Evaluation License](https://neo4j.com/terms/enterprise_us/),
398-
with 30 days trial period.
399-
Please read and agree the license before starting the instance.
400-
401-
:::
389+
#### Spec
402390

403391
The `Neo4j` target spec takes the following fields:
404392

@@ -417,17 +405,32 @@ Neo4j also provides a declaration spec `Neo4jDeclaration`, to configure indexing
417405
* `primary_key_fields` (required)
418406
* `vector_indexes` (optional)
419407

420-
### Kuzu
408+
#### Neo4j dev instance
421409

422-
CocoIndex supports talking to Kuzu through its [API server](https://github.com/kuzudb/api-server).
423-
You can bring up a Kuzu API server locally by running:
410+
If you don't have a Neo4j database, you can start a Neo4j database using our docker compose config:
424411

425412
```bash
426-
KUZU_DB_DIR=$HOME/.kuzudb
427-
KUZU_PORT=8123
428-
docker run -d --name kuzu -p ${KUZU_PORT}:8000 -v ${KUZU_DB_DIR}:/database kuzudb/api-server:latest
413+
docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex/refs/heads/main/dev/neo4j.yaml) up -d
429414
```
430415

416+
If will bring up a Neo4j instance, which can be accessed by username `neo4j` and password `cocoindex`.
417+
You can access the Neo4j browser at [http://localhost:7474](http://localhost:7474).
418+
419+
:::warning
420+
421+
The docker compose config above will start a Neo4j Enterprise instance under the [Evaluation License](https://neo4j.com/terms/enterprise_us/),
422+
with 30 days trial period.
423+
Please read and agree the license before starting the instance.
424+
425+
:::
426+
427+
428+
### Kuzu
429+
430+
#### Spec
431+
432+
CocoIndex supports talking to Kuzu through its [API server](https://github.com/kuzudb/api-server).
433+
431434
The `Kuzu` target spec takes the following fields:
432435

433436
* `connection` (type: [auth reference](../core/flow_def#auth-registry) to `KuzuConnectionSpec`): The connection to the Kuzu database. `KuzuConnectionSpec` has the following fields:
@@ -440,3 +443,25 @@ Kuzu also provides a declaration spec `KuzuDeclaration`, to configure indexing o
440443
* Fields for [nodes to declare](#declare-extra-node-labels), including
441444
* `nodes_label` (required)
442445
* `primary_key_fields` (required)
446+
447+
#### Kuzu dev instance
448+
449+
If you don't have a Kuzu instance yet, you can bring up a Kuzu API server locally by running:
450+
451+
```bash
452+
KUZU_DB_DIR=$HOME/.kuzudb
453+
KUZU_PORT=8123
454+
docker run -d --name kuzu -p ${KUZU_PORT}:8000 -v ${KUZU_DB_DIR}:/database kuzudb/api-server:latest
455+
```
456+
457+
To explore the graph you built with Kuzu, you can use the [Kuzu Explorer](https://github.com/kuzudb/explorer).
458+
Currently Kuzu API server and the explorer cannot be up at the same time. So you need to stop the API server before running the explorer.
459+
460+
To start the instance of the explorer, run:
461+
462+
```bash
463+
KUZU_EXPLORER_PORT=8124
464+
docker run -d --name kuzu-explorer -p ${KUZU_EXPLORER_PORT}:8000 -v ${KUZU_DB_DIR}:/database -e MODE=READ_ONLY kuzudb/explorer:latest
465+
```
466+
467+
You can then access the explorer at [http://localhost:8124](http://localhost:8124).

‎examples/docs_to_knowledge_graph/README.md‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,10 @@ Please drop [Cocoindex on Github](https://github.com/cocoindex-io/cocoindex) a s
1212

1313
![example-explanation](https://github.com/user-attachments/assets/07ddbd60-106f-427f-b7cc-16b73b142d27)
1414

15-
1615
## Prerequisite
1716
* [Install Postgres](https://cocoindex.io/docs/getting_started/installation#-install-postgres) if you don't have one.
18-
* [Install Neo4j](https://cocoindex.io/docs/ops/storages#neo4j) if you don't have one.
17+
* Install [Neo4j](https://cocoindex.io/docs/ops/storages#neo4j-dev-instance) or [Kuzu](https://cocoindex.io/docs/ops/storages#kuzu-dev-instance) if you don't have one.
18+
* The example uses Neo4j by default for now. If you want to use Kuzu, find out the "SELECT ONE GRAPH DATABASE TO USE" section and switch the active branch.
1919
* [Configure your OpenAI API key](https://cocoindex.io/docs/ai/llm#openai).
2020

2121
## Documentation
@@ -45,21 +45,18 @@ cocoindex update main.py
4545

4646
### Browse the knowledge graph
4747

48-
After the knowledge graph is build, you can explore the knowledge graph you built in Neo4j Browser.
48+
After the knowledge graph is built, you can explore the knowledge graph.
4949

50-
For the dev enviroment, you can connect neo4j browser using credentials:
51-
- username: `neo4j`
52-
- password: `cocoindex`
53-
which is pre-configured in the our docker compose [config.yaml](https://raw.githubusercontent.com/cocoindex-io/cocoindex/refs/heads/main/dev/neo4j.yaml).
50+
* If you're using Neo4j, you can open the explorer at [http://localhost:7474](http://localhost:7474), with username `neo4j` and password `cocoindex`.
51+
* If you're using Kuzu, you can start a Kuzu explorer locally. See [Kuzu dev instance](https://cocoindex.io/docs/ops/storages#kuzu-dev-instance) for more details.
5452

55-
You can open it at [http://localhost:7474](http://localhost:7474), and run the following Cypher query to get all relationships:
53+
You can run the following Cypher query to get all relationships:
5654

5755
```cypher
5856
MATCH p=()-->() RETURN p
5957
```
60-
<img width="1366" alt="neo4j-for-coco-docs" src="https://github.com/user-attachments/assets/3c8b6329-6fee-4533-9480-571399b57e57" />
61-
6258

59+
<img width="1366" alt="neo4j-for-coco-docs" src="https://github.com/user-attachments/assets/3c8b6329-6fee-4533-9480-571399b57e57" />
6360

6461
## CocoInsight
6562
I used CocoInsight (Free beta now) to troubleshoot the index generation and understand the data lineage of the pipeline.

‎examples/docs_to_knowledge_graph/main.py‎

Lines changed: 26 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -5,27 +5,6 @@
55
import dataclasses
66
import cocoindex
77

8-
9-
@dataclasses.dataclass
10-
class DocumentSummary:
11-
"""Describe a summary of a document."""
12-
13-
title: str
14-
summary: str
15-
16-
17-
@dataclasses.dataclass
18-
class Relationship:
19-
"""
20-
Describe a relationship between two entities.
21-
Subject and object should be Core CocoIndex concepts only, should be nouns. For example, `CocoIndex`, `Incremental Processing`, `ETL`, `Data` etc.
22-
"""
23-
24-
subject: str
25-
predicate: str
26-
object: str
27-
28-
298
neo4j_conn_spec = cocoindex.add_auth_entry(
309
"Neo4jConnection",
3110
cocoindex.storages.Neo4jConnection(
@@ -41,19 +20,43 @@ class Relationship:
4120
),
4221
)
4322

44-
# Use Neo4j as the graph database
23+
# SELECT ONE GRAPH DATABASE TO USE
24+
# This example can use either Neo4j or Kuzu as the graph database.
25+
# Please make sure only one branch is live and others are commented out.
26+
27+
# Use Neo4j
4528
GraphDbSpec = cocoindex.storages.Neo4j
4629
GraphDbConnection = cocoindex.storages.Neo4jConnection
4730
GraphDbDeclaration = cocoindex.storages.Neo4jDeclaration
4831
conn_spec = neo4j_conn_spec
4932

50-
# Use Kuzu as the graph database
33+
# Use Kuzu
5134
# GraphDbSpec = cocoindex.storages.Kuzu
5235
# GraphDbConnection = cocoindex.storages.KuzuConnection
5336
# GraphDbDeclaration = cocoindex.storages.KuzuDeclaration
5437
# conn_spec = kuzu_conn_spec
5538

5639

40+
@dataclasses.dataclass
41+
class DocumentSummary:
42+
"""Describe a summary of a document."""
43+
44+
title: str
45+
summary: str
46+
47+
48+
@dataclasses.dataclass
49+
class Relationship:
50+
"""
51+
Describe a relationship between two entities.
52+
Subject and object should be Core CocoIndex concepts only, should be nouns. For example, `CocoIndex`, `Incremental Processing`, `ETL`, `Data` etc.
53+
"""
54+
55+
subject: str
56+
predicate: str
57+
object: str
58+
59+
5760
@cocoindex.flow_def(name="DocsToKG")
5861
def docs_to_kg_flow(
5962
flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataScope

‎examples/product_recommendation/README.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ Please drop [CocoIndex on Github](https://github.com/cocoindex-io/cocoindex) a s
99

1010
## Prerequisite
1111
* [Install Postgres](https://cocoindex.io/docs/getting_started/installation#-install-postgres) if you don't have one.
12-
* [Install Neo4j](https://cocoindex.io/docs/ops/storages#neo4j) if you don't have one.
12+
* Install [Neo4j](https://cocoindex.io/docs/ops/storages#neo4j-dev-instance) or [Kuzu](https://cocoindex.io/docs/ops/storages#kuzu-dev-instance) if you don't have one.
13+
* The example uses Neo4j by default for now. If you want to use Kuzu, find out the "SELECT ONE GRAPH DATABASE TO USE" section and switch the active branch.
1314
* [Configure your OpenAI API key](https://cocoindex.io/docs/ai/llm#openai).
1415

1516
## Documentation
@@ -39,18 +40,17 @@ cocoindex update main.py
3940

4041
### Browse the knowledge graph
4142

42-
After the knowledge graph is built, you can explore the knowledge graph you built in Neo4j Browser.
43+
After the knowledge graph is built, you can explore the knowledge graph.
4344

44-
For the dev enviroment, you can connect neo4j browser using credentials:
45-
- username: `neo4j`
46-
- password: `cocoindex`
47-
which is pre-configured in the our docker compose [config.yaml](https://raw.githubusercontent.com/cocoindex-io/cocoindex/refs/heads/main/dev/neo4j.yaml).
45+
* If you're using Neo4j, you can open the explorer at [http://localhost:7474](http://localhost:7474), with username `neo4j` and password `cocoindex`.
46+
* If you're using Kuzu, you can start a Kuzu explorer locally. See [Kuzu dev instance](https://cocoindex.io/docs/ops/storages#kuzu-dev-instance) for more details.
4847

49-
You can open it at [http://localhost:7474](http://localhost:7474), and run the following Cypher query to get all relationships:
48+
You can run the following Cypher query to get all relationships:
5049

5150
```cypher
5251
MATCH p=()-->() RETURN p
5352
```
53+
5454
![Neo4j Browser Screenshot](img/neo4j.png)
5555

5656
## CocoInsight

‎examples/product_recommendation/main.py‎

Lines changed: 32 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,38 @@
77
import cocoindex
88
from jinja2 import Template
99

10+
neo4j_conn_spec = cocoindex.add_auth_entry(
11+
"Neo4jConnection",
12+
cocoindex.storages.Neo4jConnection(
13+
uri="bolt://localhost:7687",
14+
user="neo4j",
15+
password="cocoindex",
16+
),
17+
)
18+
kuzu_conn_spec = cocoindex.add_auth_entry(
19+
"KuzuConnection",
20+
cocoindex.storages.KuzuConnection(
21+
api_server_url="http://localhost:8123",
22+
),
23+
)
24+
25+
# SELECT ONE GRAPH DATABASE TO USE
26+
# This example can use either Neo4j or Kuzu as the graph database.
27+
# Please make sure only one branch is live and others are commented out.
28+
29+
# Use Neo4j
30+
GraphDbSpec = cocoindex.storages.Neo4j
31+
GraphDbConnection = cocoindex.storages.Neo4jConnection
32+
GraphDbDeclaration = cocoindex.storages.Neo4jDeclaration
33+
conn_spec = neo4j_conn_spec
34+
35+
# Use Kuzu
36+
# GraphDbSpec = cocoindex.storages.Kuzu
37+
# GraphDbConnection = cocoindex.storages.KuzuConnection
38+
# GraphDbDeclaration = cocoindex.storages.KuzuDeclaration
39+
# conn_spec = kuzu_conn_spec
40+
41+
1042
# Template for rendering product information as markdown to provide information to LLMs
1143
PRODUCT_TEMPLATE = """
1244
# {{ title }}
@@ -77,34 +109,6 @@ def extract_product_info(product: cocoindex.Json, filename: str) -> ProductInfo:
77109
)
78110

79111

80-
neo4j_conn_spec = cocoindex.add_auth_entry(
81-
"Neo4jConnection",
82-
cocoindex.storages.Neo4jConnection(
83-
uri="bolt://localhost:7687",
84-
user="neo4j",
85-
password="cocoindex",
86-
),
87-
)
88-
kuzu_conn_spec = cocoindex.add_auth_entry(
89-
"KuzuConnection",
90-
cocoindex.storages.KuzuConnection(
91-
api_server_url="http://localhost:8123",
92-
),
93-
)
94-
95-
# Use Neo4j as the graph database
96-
GraphDbSpec = cocoindex.storages.Neo4j
97-
GraphDbConnection = cocoindex.storages.Neo4jConnection
98-
GraphDbDeclaration = cocoindex.storages.Neo4jDeclaration
99-
conn_spec = neo4j_conn_spec
100-
101-
# Use Kuzu as the graph database
102-
# GraphDbSpec = cocoindex.storages.Kuzu
103-
# GraphDbConnection = cocoindex.storages.KuzuConnection
104-
# GraphDbDeclaration = cocoindex.storages.KuzuDeclaration
105-
# conn_spec = kuzu_conn_spec
106-
107-
108112
@cocoindex.flow_def(name="StoreProduct")
109113
def store_product_flow(
110114
flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataScope

0 commit comments

Comments
 (0)