cameron.stream
A Claude-written graph database in Rust. Use at your own risk.
1# Basic Operations Examples
2
3This guide covers fundamental operations in GigaBrain: creating nodes, relationships, and running basic queries.
4
5## Table of Contents
6
7- [Setup](#setup)
8- [Node Operations](#node-operations)
9- [Relationship Operations](#relationship-operations)
10- [Basic Queries](#basic-queries)
11- [Property Management](#property-management)
12- [Error Handling](#error-handling)
13
14## Setup
15
16Ensure GigaBrain server is running:
17
18```bash
19cargo run --bin gigabrain
20```
21
22The server will start with:
23- REST API on port 3000
24- gRPC API on port 50051
25
26## Node Operations
27
28### Creating Nodes
29
30#### Simple Node Creation
31
32```bash
33# Create a person node
34curl -X POST http://localhost:3000/api/v1/nodes \
35 -H "Content-Type: application/json" \
36 -d '{
37 "labels": ["Person"],
38 "properties": [
39 {
40 "key": "name",
41 "value": {"string_value": "Alice Johnson"}
42 },
43 {
44 "key": "age",
45 "value": {"int_value": 28}
46 },
47 {
48 "key": "email",
49 "value": {"string_value": "alice@example.com"}
50 }
51 ]
52 }'
53```
54
55**Expected Response:**
56```json
57{
58 "node_id": {
59 "id": 1
60 }
61}
62```
63
64#### Node with Multiple Labels
65
66```bash
67# Create a person who is also an employee
68curl -X POST http://localhost:3000/api/v1/nodes \
69 -H "Content-Type: application/json" \
70 -d '{
71 "labels": ["Person", "Employee"],
72 "properties": [
73 {
74 "key": "name",
75 "value": {"string_value": "Bob Smith"}
76 },
77 {
78 "key": "employee_id",
79 "value": {"string_value": "EMP001"}
80 },
81 {
82 "key": "salary",
83 "value": {"float_value": 75000.0}
84 },
85 {
86 "key": "active",
87 "value": {"bool_value": true}
88 }
89 ]
90 }'
91```
92
93### Retrieving Nodes
94
95```bash
96# Get node by ID
97curl http://localhost:3000/api/v1/nodes/1
98```
99
100**Expected Response:**
101```json
102{
103 "node": {
104 "id": {"id": 1},
105 "labels": ["Person"],
106 "properties": [
107 {
108 "key": "name",
109 "value": {"string_value": "Alice Johnson"}
110 },
111 {
112 "key": "age",
113 "value": {"int_value": 28}
114 },
115 {
116 "key": "email",
117 "value": {"string_value": "alice@example.com"}
118 }
119 ]
120 }
121}
122```
123
124### Updating Nodes
125
126```bash
127# Update node properties
128curl -X PUT http://localhost:3000/api/v1/nodes/1 \
129 -H "Content-Type: application/json" \
130 -d '{
131 "node_id": {"id": 1},
132 "labels": ["Person", "Customer"],
133 "properties": [
134 {
135 "key": "name",
136 "value": {"string_value": "Alice Johnson-Smith"}
137 },
138 {
139 "key": "age",
140 "value": {"int_value": 29}
141 },
142 {
143 "key": "status",
144 "value": {"string_value": "premium"}
145 }
146 ]
147 }'
148```
149
150### Deleting Nodes
151
152```bash
153# Delete a node
154curl -X DELETE http://localhost:3000/api/v1/nodes/1
155```
156
157**Expected Response:**
158```json
159{
160 "success": true
161}
162```
163
164## Relationship Operations
165
166### Creating Relationships
167
168#### Basic Relationship
169
170```bash
171# Create friendship relationship
172curl -X POST http://localhost:3000/api/v1/relationships \
173 -H "Content-Type: application/json" \
174 -d '{
175 "start_node": {"id": 1},
176 "end_node": {"id": 2},
177 "rel_type": "FRIENDS",
178 "properties": [
179 {
180 "key": "since",
181 "value": {"string_value": "2023-01-15"}
182 },
183 {
184 "key": "closeness",
185 "value": {"float_value": 0.8}
186 }
187 ]
188 }'
189```
190
191#### Work Relationship
192
193```bash
194# Create employment relationship
195curl -X POST http://localhost:3000/api/v1/relationships \
196 -H "Content-Type: application/json" \
197 -d '{
198 "start_node": {"id": 2},
199 "end_node": {"id": 3},
200 "rel_type": "WORKS_FOR",
201 "properties": [
202 {
203 "key": "position",
204 "value": {"string_value": "Software Engineer"}
205 },
206 {
207 "key": "start_date",
208 "value": {"string_value": "2022-03-01"}
209 },
210 {
211 "key": "remote",
212 "value": {"bool_value": true}
213 }
214 ]
215 }'
216```
217
218### Retrieving Relationships
219
220```bash
221# Get relationship by ID
222curl http://localhost:3000/api/v1/relationships/1
223```
224
225**Expected Response:**
226```json
227{
228 "relationship": {
229 "id": {"id": 1},
230 "start_node": {"id": 1},
231 "end_node": {"id": 2},
232 "rel_type": "FRIENDS",
233 "properties": [
234 {
235 "key": "since",
236 "value": {"string_value": "2023-01-15"}
237 },
238 {
239 "key": "closeness",
240 "value": {"float_value": 0.8}
241 }
242 ]
243 }
244}
245```
246
247### Deleting Relationships
248
249```bash
250# Delete a relationship
251curl -X DELETE http://localhost:3000/api/v1/relationships/1
252```
253
254## Basic Queries
255
256### Simple Queries
257
258#### Find All Nodes
259
260```bash
261curl -X POST http://localhost:3000/api/v1/cypher \
262 -H "Content-Type: application/json" \
263 -d '{
264 "query": "MATCH (n) RETURN n LIMIT 10"
265 }'
266```
267
268#### Find Nodes by Label
269
270```bash
271curl -X POST http://localhost:3000/api/v1/cypher \
272 -H "Content-Type: application/json" \
273 -d '{
274 "query": "MATCH (p:Person) RETURN p.name, p.age ORDER BY p.age DESC"
275 }'
276```
277
278#### Find Relationships
279
280```bash
281curl -X POST http://localhost:3000/api/v1/cypher \
282 -H "Content-Type: application/json" \
283 -d '{
284 "query": "MATCH (a)-[r:FRIENDS]->(b) RETURN a.name, r.since, b.name"
285 }'
286```
287
288### Parameterized Queries
289
290```bash
291curl -X POST http://localhost:3000/api/v1/cypher \
292 -H "Content-Type: application/json" \
293 -d '{
294 "query": "MATCH (p:Person) WHERE p.age > $min_age RETURN p.name, p.age",
295 "parameters": {
296 "min_age": 25
297 }
298 }'
299```
300
301### Complex Queries
302
303#### Find Friends of Friends
304
305```bash
306curl -X POST http://localhost:3000/api/v1/cypher \
307 -H "Content-Type: application/json" \
308 -d '{
309 "query": "MATCH (p:Person {name: $name})-[:FRIENDS]-(friend)-[:FRIENDS]-(fof) WHERE fof <> p RETURN DISTINCT fof.name",
310 "parameters": {
311 "name": "Alice Johnson"
312 }
313 }'
314```
315
316#### Find Colleagues
317
318```bash
319curl -X POST http://localhost:3000/api/v1/cypher \
320 -H "Content-Type: application/json" \
321 -d '{
322 "query": "MATCH (p:Person)-[:WORKS_FOR]->(company)<-[:WORKS_FOR]-(colleague) WHERE p.name = $name AND colleague <> p RETURN colleague.name, colleague.employee_id",
323 "parameters": {
324 "name": "Bob Smith"
325 }
326 }'
327```
328
329## Property Management
330
331### Property Types
332
333GigaBrain supports various property types:
334
335```bash
336# String properties
337{
338 "key": "name",
339 "value": {"string_value": "John Doe"}
340}
341
342# Integer properties
343{
344 "key": "age",
345 "value": {"int_value": 30}
346}
347
348# Float properties
349{
350 "key": "score",
351 "value": {"float_value": 85.5}
352}
353
354# Boolean properties
355{
356 "key": "active",
357 "value": {"bool_value": true}
358}
359
360# Binary data
361{
362 "key": "avatar",
363 "value": {"bytes_value": "base64-encoded-data"}
364}
365```
366
367### Property Queries
368
369#### Filter by Property Value
370
371```bash
372curl -X POST http://localhost:3000/api/v1/cypher \
373 -H "Content-Type: application/json" \
374 -d '{
375 "query": "MATCH (p:Person) WHERE p.age >= 25 AND p.age <= 35 RETURN p.name, p.age"
376 }'
377```
378
379#### Property Existence
380
381```bash
382curl -X POST http://localhost:3000/api/v1/cypher \
383 -H "Content-Type: application/json" \
384 -d '{
385 "query": "MATCH (p:Person) WHERE EXISTS(p.email) RETURN p.name, p.email"
386 }'
387```
388
389#### String Operations
390
391```bash
392curl -X POST http://localhost:3000/api/v1/cypher \
393 -H "Content-Type: application/json" \
394 -d '{
395 "query": "MATCH (p:Person) WHERE p.name CONTAINS $substring RETURN p.name",
396 "parameters": {
397 "substring": "John"
398 }
399 }'
400```
401
402### Updating Properties
403
404#### Add New Property
405
406```bash
407curl -X POST http://localhost:3000/api/v1/cypher \
408 -H "Content-Type: application/json" \
409 -d '{
410 "query": "MATCH (p:Person {name: $name}) SET p.last_login = $timestamp RETURN p",
411 "parameters": {
412 "name": "Alice Johnson",
413 "timestamp": "2024-01-15T10:30:00Z"
414 }
415 }'
416```
417
418#### Remove Property
419
420```bash
421curl -X POST http://localhost:3000/api/v1/cypher \
422 -H "Content-Type: application/json" \
423 -d '{
424 "query": "MATCH (p:Person {name: $name}) REMOVE p.temporary_field RETURN p",
425 "parameters": {
426 "name": "Alice Johnson"
427 }
428 }'
429```
430
431## Error Handling
432
433### Common Error Scenarios
434
435#### Node Not Found
436
437```bash
438curl http://localhost:3000/api/v1/nodes/999999
439```
440
441**Response (404):**
442```json
443{
444 "error": {
445 "code": "NOT_FOUND",
446 "message": "Node not found",
447 "details": {}
448 }
449}
450```
451
452#### Invalid Property Type
453
454```bash
455curl -X POST http://localhost:3000/api/v1/nodes \
456 -H "Content-Type: application/json" \
457 -d '{
458 "labels": ["Person"],
459 "properties": [
460 {
461 "key": "age",
462 "value": {"string_value": "not a number"}
463 }
464 ]
465 }'
466```
467
468#### Syntax Error in Cypher
469
470```bash
471curl -X POST http://localhost:3000/api/v1/cypher \
472 -H "Content-Type: application/json" \
473 -d '{
474 "query": "MATCH (n) RETURN invalid_syntax"
475 }'
476```
477
478**Response:**
479```json
480{
481 "results": [],
482 "error": "Parse error: unexpected token 'invalid_syntax'",
483 "execution_time_ms": 0
484}
485```
486
487### Error Handling Best Practices
488
4891. **Check HTTP Status Codes**: Always verify the response status
4902. **Parse Error Messages**: Extract meaningful error information
4913. **Retry Logic**: Implement appropriate retry strategies
4924. **Validation**: Validate input data before sending requests
4935. **Logging**: Log errors for debugging and monitoring
494
495### Example Error Handling (Python)
496
497```python
498import requests
499import json
500
501def safe_create_node(labels, properties):
502 try:
503 response = requests.post(
504 "http://localhost:3000/api/v1/nodes",
505 headers={"Content-Type": "application/json"},
506 json={"labels": labels, "properties": properties},
507 timeout=10
508 )
509
510 if response.status_code == 200:
511 return response.json()
512 elif response.status_code == 400:
513 error = response.json().get('error', {})
514 print(f"Validation error: {error.get('message', 'Unknown error')}")
515 return None
516 elif response.status_code == 500:
517 print("Server error occurred")
518 return None
519 else:
520 print(f"Unexpected status code: {response.status_code}")
521 return None
522
523 except requests.exceptions.Timeout:
524 print("Request timed out")
525 return None
526 except requests.exceptions.ConnectionError:
527 print("Could not connect to server")
528 return None
529 except json.JSONDecodeError:
530 print("Invalid JSON response")
531 return None
532
533# Usage
534result = safe_create_node(
535 ["Person"],
536 [{"key": "name", "value": {"string_value": "Test User"}}]
537)
538
539if result:
540 print(f"Created node: {result}")
541else:
542 print("Failed to create node")
543```
544
545## Performance Tips
546
5471. **Use Indexes**: Create indexes on frequently queried properties
5482. **Limit Results**: Always use LIMIT in development and test queries
5493. **Batch Operations**: Group multiple operations when possible
5504. **Property Selection**: Only return properties you need
5515. **Query Planning**: Analyze query execution plans for optimization
552
553## Next Steps
554
555- Explore [Social Network Examples](./social-network.md)
556- Learn about [Graph Algorithms](../API.md#graph-algorithms)
557- Check out [Performance Testing](./performance-testing.md)
558- Review [gRPC Examples](./grpc-examples.md)