@spec create_dense_index(
  Arcadic.Conn.t(),
  String.t(),
  String.t(),
  pos_integer(),
  keyword()
) ::
  :ok | {:error, atom() | Exception.t()}

Creates a dense LSM_VECTOR index (idempotent — IF NOT EXISTS). opts: similarity (:cosine default | :dot_product | :euclidean), encoding (:float32 | :int8), quantization (:none | :int8 | :binary | :product), max_connections (default 16), beam_width (default 100). Unknown opt keys are rejected value-free (the server silently accepts unknown METADATA keys).

@spec create_dense_index!(
  Arcadic.Conn.t(),
  String.t(),
  String.t(),
  pos_integer(),
  keyword()
) :: :ok

Creates a dense vector index, raising on error.

@spec drop_dense_index(Arcadic.Conn.t(), String.t(), String.t()) ::
  :ok | {:error, atom() | Exception.t()}

Drops a dense vector index (idempotent — IF EXISTS).

@spec drop_dense_index!(Arcadic.Conn.t(), String.t(), String.t()) :: :ok

Drops a dense vector index, raising on error.

@spec fuse(
  Arcadic.Conn.t(),
  [{String.t(), String.t(), [number()], pos_integer()}],
  keyword()
) ::
  {:ok, [map()]} | {:error, atom() | Exception.t()}

Runs a hybrid fusion over dense neighbour subqueries. neighbor_specs is a non-empty list of {type, property, query_vector, k}, each built as a validated vector.neighbors subquery with distinct indexed params. opts: fusion (:rrf default | :dbsf | :linear), weights (list of numbers), k (pos_integer).

Fused rows are ranked by ArcadeDB's fusion score (higher = better) rather than the distance that neighbors/6 returns.

neighbor_specs and weights are trusted developer-supplied config: the emitted statement grows linearly with their length (no cap), matching arcadic's no-statement-size-limit posture elsewhere.

@spec fuse!(
  Arcadic.Conn.t(),
  [{String.t(), String.t(), [number()], pos_integer()}],
  keyword()
) :: [
  map()
]

Runs a hybrid fusion, returning rows or raising.

@spec index_ref(String.t(), String.t()) ::
  {:ok, String.t()} | {:error, :invalid_identifier}

Builds the ArcadeDB index reference "Type[property]", validating both identifiers.

@spec neighbors(
  Arcadic.Conn.t(),
  String.t(),
  String.t(),
  [number()],
  pos_integer(),
  keyword()
) ::
  {:ok, [map()]} | {:error, atom() | Exception.t()}

Runs a dense nearest-neighbour search, returning rows ranked closest-first (each carries the vertex's top-level fields plus distance). query_vector and k bind as params. opts: ef_search (pos_integer), max_distance (number) — both bind as params inside the query-options object.

distance (and therefore max_distance) semantics depend on the index's similarity: COSINE yields 0..1 ascending (0 = identical); DOT_PRODUCT yields NEGATIVE values (≈ -1 identical, less-negative = farther), so a small positive max_distance filters nothing; EUCLIDEAN differs again. Choose thresholds per the index's similarity.

@spec neighbors!(
  Arcadic.Conn.t(),
  String.t(),
  String.t(),
  [number()],
  pos_integer(),
  keyword()
) :: [
  map()
]

Runs a dense nearest-neighbour search, returning rows or raising.