https://github.com/jgaskins/falkordb
Crystal client for the FalkorDB graph database built on top of Redis
https://github.com/jgaskins/falkordb
falkordb graph-database
Last synced: 2 months ago
JSON representation
Crystal client for the FalkorDB graph database built on top of Redis
- Host: GitHub
- URL: https://github.com/jgaskins/falkordb
- Owner: jgaskins
- License: mit
- Created: 2025-07-05T02:02:26.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-07-05T02:39:41.000Z (3 months ago)
- Last Synced: 2025-08-04T03:55:17.021Z (2 months ago)
- Topics: falkordb, graph-database
- Language: Crystal
- Homepage:
- Size: 17.6 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# FalkorDB
This shard is a Crystal client for [FalkorDB](https://www.falkordb.com), a graph database built on top of Redis.
## Installation
1. Add the dependency to your `shard.yml`:
```yaml
dependencies:
falkordb:
github: jgaskins/falkordb
```
2. Run `shards install`
## Usage
```crystal
require "falkordb"
redis = Redis::Client.new
graph = FalkorDB::Graph.new(redis, "your-graph-key")
```
Then, when you run your queries, use the `read_query` and `write_query` methods. If you're using a `Redis::ReplicationClient`, this will automatically route write queries to the primary and read queries to replicas.
```crystal
graph.write_query <<-CYPHER
CREATE (user:User {
id: randomUUID(),
name: "Jamie"
})
CYPHER
```
### Specifying query return type
You can set the return type of the results using the `return:` argument. This must match the types of the values in your Cypher query's `RETURN` clause.
```crystal
# We need to get the first result from the result set to get the id itself
id = graph.write_query(<<-CYPHER, return: UUID).first
CREATE (user:User {
id: randomUUID(),
name: "Jamie"
})
RETURN user.id
CYPHER
```
### Returning multiple values per result
If your `RETURN` clause has multiple values, you can specify their types using tuples:
```crystal
graph.read_query(<<-CYPHER, return: {User, Team})
MATCH (user:User)-[:MEMBER_OF]->(team:Team)
RETURN user, team
CYPHER
```
### Passing query parameters
If you need to pass values to your query, it's best to use query parameters rather than interpolate them into the strings. This offers the same benefits as for SQL databases:
- Improved performance via caching query plans
- Avoiding query injection via malformed values
To pass query parameters, simply place them after your Cypher query. For example, to get all of the teams the current user is a member of, you might use a query that looks like this:
```crystal
graph.read_query <<-CYPHER, {user_id: current_user.id}, return: Team do |team|
MATCH (user:User{id: $user_id})-[:MEMBER_OF]->(team:Team)
RETURN team
CYPHER
```
### Defining custom node/relationship types
You can represent nodes and relationships in your graph using your own Crystal types with certain properties automatically deserialized into other types for you. For example, let's say you have a `Post` type:
```crystal
struct Post
include FalkorDB::Serializable::Node
getter id : UUID
getter body : String
getter created_at : Time
end
```
If your `id` is stored as a string (generated with the [`randomUUID()` function](https://docs.falkordb.com/cypher/functions.html#scalar-functions), for example) and your `created_at` property is stored as a Unix millisecond timestamp (via [`Time#to_unix_ms`](https://crystal-lang.org/api/1.16.3/Time.html#to_unix_ms:Int64-instance-method)), this post can be automatically deserialized:
```crystal
graph.read_query(<<-CYPHER, return: Post).each do |post|
MATCH (post:Post)
RETURN post
CYPHER
# ...
end
```
## Contributing
1. Fork it ()
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
## Contributors
- [Jamie Gaskins](https://github.com/jgaskins) - creator and maintainer