@spec ast_clones(
  [String.t() | Dllb.MetaAST.meta_ast_node()],
  keyword()
) :: String.t()

Detects near-duplicate (fuzzy) clones among the given AST trees using the server-side ast::clones function -- the native-Rust counterpart to Dllb.MetaAST.Similarity.find_clones/2.

asts is a list of serialized JSON strings and/or Metastatic AST node 3-tuples (tuples are automatically serialized). Every SELECT requires a FROM target, so this anchors on an arbitrary row of ast_node (its stored content is not inspected) -- at least one row must already exist in the table. The result row carries a clones field: a JSON-encoded list of %{"index_a" => i, "index_b" => j, "similarity" => score} pairs.

Options

• :threshold - minimum similarity to report (default 0.8)

@spec ast_diff(
  String.t() | Dllb.MetaAST.meta_ast_node(),
  keyword()
) :: String.t()

Computes a structural diff between each AST node's stored tree and a target tree, using the server-side ast::diff function (native Rust) -- the engine-side counterpart to Dllb.MetaAST.Diff.diff_trees/2.

The target can be a serialized JSON string or a Metastatic AST node 3-tuple (which will be automatically serialized to JSON). Each result row carries a diff field: a JSON-encoded summary with changes, added, removed, modified, and renamed keys.

Prefer Dllb.MetaAST.Diff.diff_trees/2 for a purely client-side diff (no round-trip); use this to delegate the comparison to already-indexed, server-side ASTs.

Options

• :limit - max results (default 10)
• :kind / :file_path / :language / :project_path - scope filters

@spec ast_scope(String.t(), non_neg_integer()) :: String.t()

Finds the AST scope path (outermost to innermost node containing line) within a single stored AST node's tree, using the server-side ast::scope function -- the engine-side counterpart to Dllb.MetaAST.QueryHelpers.scope_at/2.

record_id must be a full table:id reference, e.g. one returned by find_function/3 or find_module/1. The result row carries a scope field: a JSON-encoded array of nodes, outermost first.

@spec call_chain(String.t(), pos_integer()) :: String.t()

Multi-hop call chain traversal from a starting node.

Builds a chained ->calls->ast_node traversal repeated depth times.

@spec callees_of(String.t()) :: String.t()

Graph traversal: find all callees of a node (outgoing calls edges).

@spec callers_of(String.t()) :: String.t()

Graph traversal: find all callers of a node (incoming calls edges).

Returns a SELECT with <-calls<-ast_node traversal syntax.

@spec complex_functions(
  pos_integer(),
  keyword()
) :: String.t()

Find AST nodes with cyclomatic complexity above a threshold, using the server-side ast::complexity function.

Options

• :limit - max results (default 10)
• :kind / :file_path / :language / :project_path - scope filters

@spec count_embeddings_query() :: String.t()

Returns a COUNT query for ast_node rows that have a source_embedding set -- i.e. the number of stored embedding vectors.

@spec delete_by_file(String.t()) :: String.t()

Builds a single-statement DELETE ast_node WHERE file_path = ... that removes every node belonging to a file in one server-side operation (secondary, full-text, and vector indexes are maintained by the engine). Pair with exec_delete_by_file/2.

@spec delete_by_project(String.t()) :: String.t()

Builds a single-statement DELETE ast_node WHERE project_path = ... that removes every node of a project in one server-side operation. Pair with exec_delete_by_project/2.

@spec duplicate_code(keyword()) :: String.t()

Find duplicate code structures that share the same Zobrist-style structural hash using the server-side ast::hash function.

Returns a query that groups nodes by their structural hash and finds groups with more than one node.

Options

• :limit - max results (default 20)
• :kind / :file_path / :language / :project_path - scope filters

@spec exec(String.t(), Dllb.MetaAST.query_fn()) :: {:ok, [map()]} | {:error, term()}

Executes a query through query_fn and returns parsed result maps.

@spec exec_count(String.t(), Dllb.MetaAST.query_fn()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Executes a COUNT query and returns {:ok, count} or {:error, reason}.

@spec exec_count_embeddings(Dllb.MetaAST.query_fn()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Counts stored embedding vectors (ast_node rows with source_embedding).

@spec exec_delete_by_file(String.t(), Dllb.MetaAST.query_fn()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Executes a native delete-by-file (DELETE ... WHERE) in a single round-trip, returning {:ok, count} (rows removed) or {:error, reason}.

@spec exec_delete_by_project(String.t(), Dllb.MetaAST.query_fn()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Executes a native delete-by-project (DELETE ... WHERE) in a single round-trip, returning {:ok, count} or {:error, reason}.

@spec exec_load_file_nodes(String.t(), Dllb.MetaAST.query_fn()) ::
  {:ok, [map()]} | {:error, term()}

Loads all nodes for a file and returns them as parsed maps.

@spec exec_stats(Dllb.MetaAST.query_fn()) :: {:ok, map()} | {:error, term()}

Executes the grouped stats query and returns {:ok, %{total: n, by_kind: %{kind => count}}}.

The grouped rows carry serde-tagged values (e.g. %{"String" => "..."}), which are unwrapped here into plain kinds and integer counts.

@spec find_function(String.t(), String.t(), non_neg_integer()) :: String.t()

SELECT a function node by module, name, and arity.

@spec find_module(String.t()) :: String.t()

SELECT a module (container) node by name.

@spec functions_of_module(
  String.t(),
  keyword()
) :: String.t()

SELECT function nodes belonging to a module.

Requires the module field to be populated during ingestion.

@spec hybrid_search(String.t(), [number()], keyword()) :: String.t()

Combined full-text + vector hybrid search via the engine's native HYBRID SEARCH verb: BM25 on source_text fused with HNSW on source_embedding. Each row carries score, text_score, and vector_score.

Options

• :limit - max results (default 10)
• :alpha - weight on the text score in 0.0..1.0 (default 0.5); the vector score gets 1 - alpha
• :kind / :file_path / :language / :project_path - optional scope filters

@spec importers_of(String.t()) :: String.t()

Graph traversal: find all modules that import a given node.

@spec imports_of(String.t()) :: String.t()

Graph traversal: find all imports of a node.

@spec nodes_by_file(
  String.t(),
  keyword()
) :: String.t()

SELECT all AST nodes belonging to a file.

@spec nodes_by_kind(
  String.t(),
  keyword()
) :: String.t()

SELECT all AST nodes of a given kind (e.g. "function_def", "container").

@spec nodes_by_project(
  String.t(),
  keyword()
) :: String.t()

SELECT nodes filtered by project path.

@spec restore_source_index() :: String.t()

Restore the source embedding HNSW index from its latest snapshot.

@spec restore_structure_index() :: String.t()

Restore the structure embedding HNSW index from its latest snapshot.

@spec search_docs(
  String.t(),
  keyword()
) :: String.t()

Full-text BM25 search on docstring, built with the engine's native SEARCH verb. Each row carries a score.

Options

• :limit - max results (default 20)

@spec search_source(
  String.t(),
  keyword()
) :: String.t()

Full-text BM25 search on source_text, built with the engine's native SEARCH verb. Each row carries a score. Requires a full-text index on source_text.

Options

• :limit - max results (default 20)
• :kind / :file_path / :language / :project_path - optional scope filters

@spec set_source_embedding(map(), [number()]) :: String.t()

Builds an UPDATE ast_node SET source_embedding = [...] WHERE <attrs> statement that attaches an embedding to the row(s) identified by attrs.

attrs is a map of column => value (e.g. %{kind: "function_def", module: "Foo", name: "bar", arity: 2}). nil values are dropped and the remaining columns are ANDed together (sorted for determinism). Targeting by stable attributes avoids reconstructing synthetic record IDs.

@spec set_structure_embedding(map(), [number()]) :: String.t()

Sets the structure embedding for AST nodes matching the given attributes.

attrs is a map of column => value used to identify the target rows.

@spec similar_by_ast(
  String.t() | Dllb.MetaAST.meta_ast_node(),
  keyword()
) :: String.t()

Find structurally similar AST nodes using the server-side ast::similarity function.

The target can be a serialized JSON string or a Metastatic AST node 3-tuple (which will be automatically serialized to JSON).

Options

• :limit - max results (default 10)
• :threshold - minimum similarity score between 0.0 and 1.0 (default 0.8)
• :kind / :file_path / :language / :project_path - scope filters

@spec similar_to(
  [number()],
  keyword()
) :: String.t()

Vector (HNSW) similarity search over source_embedding, built with the engine's native VECTOR SEARCH verb. Results come back nearest-first, each row carrying a distance field. Requires a vector index on source_embedding (see Dllb.Schema.ast_node_search_indexes/0).

Options

• :limit - max results (default 10)
• :kind - optional kind filter (scopes results server-side)
• :file_path - optional file filter
• :language - optional language filter
• :project_path - optional project filter (multi-project isolation)

@spec snapshot_source_index() :: String.t()

Trigger a snapshot of the source embedding HNSW index to persistent storage.

@spec snapshot_structure_index() :: String.t()

Trigger a snapshot of the structure embedding HNSW index to persistent storage.

@spec source_index_info() :: String.t()

Get info about the source embedding HNSW index.

@spec stats_query() :: String.t()

Returns a COUNT ast_node GROUP BY kind query: one row per kind, each carrying a count, aggregated server-side.

@spec structurally_similar_to(
  [number()],
  keyword()
) :: String.t()

Find structurally similar AST nodes using structure_embedding vector search.

Requires a vector index on structure_embedding and that structure embeddings have been generated (via Dllb.MetaAST.Similarity.subtree_hash/1 or a learned embedding).

Options

• :limit - max results (default 10)
• :kind / :file_path / :language / :project_path - scope filters

@spec structure_index_info() :: String.t()

Get info about the structure embedding HNSW index.