us.whitford.fulcro.rad.database-adapters.datalevin-options — us.whitford/fulcro-rad-datalevin 1.0.0-RC2

Options and configuration keys for Datalevin database adapter.

all-ids-key clj/s

Qualified keyword. Renames the output key of the generated all-ids enumeration resolver (mirrors the datomic adapter's indexed-access-options/resolver-key naming-override idiom). Only honored alongside ::all-resolver? true — the flag gates generation, this key names it; on its own it generates nothing.

Use when :<ns>/all already means something else in your graph — e.g. your own :page/all resolver enumerates an external truth-source while the generated one enumerates the Datalevin index; two truth-sources must not share one output key.

Example:

(defattr id :page/id :uuid
  {::attr/identity?    true
   ::dlo/all-resolver? true
   ::dlo/all-ids-key   :page/index-all}) ; => :page/index-all
                                         ;    (:page/all stays yours)

all-resolver? clj/s

Boolean identity-attribute option gating generation of the :<ns>/all enumeration resolver. Following the canonical RAD adapter idiom (datomic, xtdb), enumeration resolvers are OPT-IN — by default only collision-safe, input-gated id-resolvers are generated.

• absent or false — no all-ids resolver is generated (default).
• true — generate it, keyed :<ns>/all (e.g. :account/all for :account/id) unless renamed via ::all-ids-key.

The generated resolver enumerates entities present in the Datalevin database. If an entity type's enumeration truth lives elsewhere (git, the filesystem, an external service), author :<ns>/all yourself and either leave this option off or rename the generated resolver with ::all-ids-key.

Example:

(defattr id :account/id :uuid
  {::attr/identity?    true
   ::dlo/all-resolver? true})  ; => :account/all

attribute-schema clj/s

Key to override/extend the generated Datalevin schema for an attribute. Value should be a map of Datalevin schema properties.

Any native Datalevin schema key may be supplied here; it is merged into (and takes precedence over) the auto-generated schema for the attribute. This is the datalevin-native way to reach features the adapter does not wrap explicitly.

Attribute predicates (:db.attr/preds) — database-side validation: Datalevin enforces :db.attr/preds on every write of the attribute. Each predicate must be a qualified symbol (or a sequential collection of them), because the schema is persisted and must be resolvable via requiring-resolve at write time — anonymous functions cannot be used. The predicate is invoked as (pred value) and must return strictly true; any other result aborts the transaction with a :transact/attr-pred error.

;; my.app.validation
(defn valid-email? [v] (boolean (re-matches #".+@.+\..+" v)))

(defattr email :account/email :string
  {::attr/identity?       true
   ::dlo/attribute-schema {:db.attr/preds 'my.app.validation/valid-email?}})

For entity-/transaction-level assertions (spanning multiple attributes), use a [:db/ensure pred & args] transaction form appended via ::raw-txn (see raw-txn).

connections clj/s

Key in Pathom env for map of schema name -> Datalevin connection

databases clj/s

Key in Pathom env for the per-request database snapshots: a map of schema-name -> atom<db>. Each value is an atom holding the current Datalevin database for that schema. wrap-env / pathom-plugin seed the atoms at request start; the save/delete middleware reset! the relevant atom to the transaction's :db-after so resolvers running later in the same request read their own writes (read-your-writes) while keeping a stable, request-scoped snapshot. Resolvers deref these values, tolerating a plain db for backward compatibility.

distance clj/s

Adapter-owned metric key: the vector distance attached to each ident map returned by a generated :<ns>/similar resolver. Lower is nearer; results are sorted ascending by this value.

Request it in the join query to receive it (it is omitted otherwise):

[{(:account/similar {:vector qv :top 10})
  [:account/id :account/name ::dlo/distance]}]

The distance is a property of the (query-vector, entity) pair — only the similar resolver that computed it can supply it.

fulltext? clj/s

Truthy. Marks the attribute as full-text searchable via Datalevin's built-in search engine. Value is either true or a map of search-domain options (e.g. {:index-position? true}, required for phrase/proximity search).

When truthy:

• Schema generation emits :db/fulltext true for the attribute.
• Unless the attribute's ::dlo/attribute-schema already specifies :db.fulltext/domains or :db.fulltext/autoDomain, the adapter derives :db.fulltext/domains [<entity-domain>], where <entity-domain> is the attribute's namespace (e.g. "account"). All searchable attributes of one entity type therefore share a single search domain.
• When the value is a map, those options are collected per domain into the :search-domains connection option by search-conn-opts and passed to d/get-conn by start-database!.

Indexing is synchronous by default (read-your-writes).

Example:

(defattr name :account/name :string
  {::attr/identities #{:account/id}
   ::dlo/fulltext?   true})

(defattr bio :account/bio :string
  {::attr/identities #{:account/id}
   ::dlo/fulltext?   {:index-position? true}})  ; enables phrase search

generate-resolvers? clj/s

Boolean. If false, automatic resolvers will not be generated for this attribute. Defaults to true.

• On an identity attribute: none of the generated resolvers for that entity type are emitted (id-resolver, all-ids, search, similar). Use when you author all resolution for the entity yourself.
• On a non-identity attribute: the attribute is omitted from the generated id-resolver's output, so you can supply it with your own resolver.

max-batch-size clj/s

Resolver-env key. Maximum number of entities fetched in a single batch query. When present it overrides the default (1000) for auto-generated id-resolvers.

native-id? clj/s

Boolean. If true, the attribute uses Datalevin's internal entity ID (:db/id) rather than a domain-specific ID. The attribute must be of type :long.

When true:

• Schema generation skips this attribute (uses built-in :db/id)
• Queries use raw entity IDs instead of lookup refs
• Results map :db/id back to this attribute's qualified key

Example:

(defattr id :person/id :long
  {::attr/identity? true
   ::dlo/native-id? true
   ::attr/schema :production})

raw-txn clj/s

Save-env key holding a vector of additional native Datalevin transaction forms to append to the generated transaction during a save. Populate it via wrap-datalevin-save/append-to-raw-txn from your own save middleware.

The primary use is entity-/transaction-level post-conditions with Datalevin's :db/ensure special form:

;; my.app.rules
(defn balance-non-negative? [db eid]
  (<= 0 (:account/balance (d/pull db [:account/balance] eid))))

;; in save middleware, before delegating to the datalevin save handler:
(dlo/append-to-raw-txn env [[:db/ensure `my.app.rules/balance-non-negative? "acct"]])

The :db/ensure predicate is invoked as (pred db-after & resolved-args); any falsey result aborts the transaction. Args may be tempids (resolved to the new entity ids), :db/current-tx, or literals.

NOTE: In a multi-schema save these forms are appended to each affected schema's transaction; reference entities that live within a single schema.

schema clj/s

The schema key used for this set of attributes. Corresponds to a key in the connections map.

score clj/s

Adapter-owned metric key: the full-text relevance score attached to each ident map returned by a generated :<ns>/search resolver. Higher is more relevant; results are sorted descending by this value.

Request it in the join query to receive it (it is omitted otherwise):

[{(:account/search {:query "fox"})
  [:account/id :account/name ::dlo/score]}]

The score is a property of the (query, entity) pair — only the search resolver that computed it can supply it.

transact-options clj/s

Save-env key. Value is passed as the tx-meta argument to Datalevin's transact! for every save transaction (Datalevin's transact! takes [conn tx-data tx-meta]). Use it to attach transaction metadata that shows up in tx reports and listen! callbacks (e.g. audit/user context).

transaction-timeout-ms clj/s

Save-env key. When present, each save transaction runs inside a Datalevin with-transaction with this per-transaction :timeout-ms; if it does not complete in time the transaction is aborted (Datalevin 1.0.0). When absent, no timeout is applied. Prefer this over the global set-explicit-transaction-timeout! for per-request control.

wrap-resolve clj/s

Identity Attribute option. A (fn [resolve]) that must return a (fn [env input]). The resolve is the core resolving logic (a function of env/input), so the returned function can manipulate the resolver inputs and outputs.

This only affects auto-generated resolvers for this identity attribute.

Example:

(defattr id :account/id :uuid
  {::attr/identity? true
   ::dlo/wrap-resolve (fn [resolve]
                        (fn [env input]
                          ;; Pre-processing
                          (let [result (resolve env input)]
                            ;; Post-processing  
                            result)))})