convex.db
Etch is a fast, immutable, append-only database specially tailored for cells.
This namespace provides an API for creating an instance by pointing to a single file. This file
hosts an arbitrarily large map of hash of the encoding of a cell -> cell. Hence, reading require
hashes (see convex.cell/hash from :project/cvm) and writes primarilty return refs or nil
when not found (see convex.ref).
Lastly, a root hash can be stored and retrieved. Cell stored at root is typically used to maintain some sort of global state or table tracking what is needed.
Attention. By default, R/W functions use the current thread-local database (see convex.cvm.db).
Providing an instance explicitly is tricky because when reading, not all data might be retrieved at once.
This is what allows large data, even larger than memory, to be queried: large structures are split into refs
and not all refs are necessarily resolved right away. However, any unresolved ref will be resolved against
the current thread-local database when needed, not the one that was explicitly provided when reading.
In other words, when handling a custom instance, it is best to work on a dedicated thread and call
convex.cvm.db/local-set.
That being said, instances support multithreading. Being immutable, no thread has to worry that some data might be removed or updated in place.
Etch is a fast, immutable, append-only database specially tailored for cells. This namespace provides an API for creating an instance by pointing to a single file. This file hosts an arbitrarily large map of `hash of the encoding of a cell` -> `cell`. Hence, reading require hashes (see `convex.cell/hash` from `:project/cvm`) and writes primarilty return refs or nil when not found (see [[convex.ref]]). Lastly, a root hash can be stored and retrieved. Cell stored at root is typically used to maintain some sort of global state or table tracking what is needed. **Attention.** By default, R/W functions use the current thread-local database (see [[convex.cvm.db]]). Providing an instance explicitly is tricky because when reading, not all data might be retrieved at once. This is what allows large data, even larger than memory, to be queried: large structures are split into refs and not all refs are necessarily resolved right away. However, any unresolved ref will be resolved against the current thread-local database when needed, not the one that was explicitly provided when reading. In other words, when handling a custom instance, it is best to work on a dedicated thread and call [[convex.cvm.db/local-set]]. That being said, instances support multithreading. Being immutable, no thread has to worry that some data might be removed or updated in place.
flushclj
(flush)(flush db)Flushes the given db, ensuring all changes are persisted to disk.
Does not work with in-memory instances.
Flushes the given `db`, ensuring all changes are persisted to disk. Does not work with in-memory instances.
openclj
(open path)Opens a db at the given path:
(open "some_dir/my-db")
File is created if needed.
Opens a db at the given `path`: ```clojure (open "some_dir/my-db") ``` File is created if needed.
open-in-memoryclj
(open-in-memory)Alternatively, an in-memory db can be used for some use cases.
However, open is typically recommended.
Alternatively, an in-memory db can be used for some use cases. However, [[open]] is typically recommended.
open-tempclj
(open-temp)(open-temp prefix)Like open but works with a temporariy file.
A prefix string may be provided.
Like [[open]] but works with a temporariy file. A prefix string may be provided.
pathclj
(path)(path db)Returns the path of the given db.
Does not work with in-memory instances.
Returns the path of the given `db`. Does not work with in-memory instances.
readclj
(read hash)(read db hash)Like read-ref but ref is directly resolved to its cell.
Convenient, but returns nil both when not found or when the stored cell is nil.
Like [[read-ref]] but ref is directly resolved to its cell. Convenient, but returns nil both when not found or when the stored cell is nil.
read-refclj
(read-ref hash)(read-ref db hash)Given a hash, reads a ref to a cell stored in the db, or nil if not found.
Given a `hash`, reads a ref to a cell stored in the `db`, or nil if not found.
read-rootclj
(read-root)(read-root db)Like read-root-ref but ref is directly resolved to its cell, akin to read.
Like [[read-root-ref]] but ref is directly resolved to its cell, akin to [[read]].
read-root-hashclj
(read-root-hash)(read-root-hash db)Reads the hash stored as root.
Reads the hash stored as root.
read-root-refclj
(read-root-ref)(read-root-ref db)Like read-ref but uses the hash from read-root-hash.
Like [[read-ref]] but uses the hash from [[read-root-hash]].
writeclj
(write cell)(write db cell)Wraps cell in a ref and calls write-ref.
Wraps `cell` in a ref and calls [[write-ref]].
write-refclj
(write-ref ref)(write-ref db ref)Given a ref, writes its associated cell.
Given a ref, writes its associated cell.
write-rootclj
(write-root cell)(write-root db cell)Wraps cell in a ref and calls write-root-ref.
Wraps `cell` in a ref and calls [[write-root-ref]].
write-root-hashclj
(write-root-hash hash)(write-root-hash db hash)Writes the given hash as root.
Writes the given `hash` as root.
write-root-refclj
(write-root-ref ref)(write-root-ref db ref)Writes ref and then sets its hash as root.
Writes `ref` and then sets its hash as root.
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close