Package ai.velr

Class Velr

java.lang.Object
ai.velr.Velr
All Implemented Interfaces:
AutoCloseable
public final class Velr extends Object implements AutoCloseable
Synchronous embedded Velr database connection.

A Velr instance owns the native database handle and any child handles opened from it: result streams, result tables, transactions, and explain traces. Close the connection when it is no longer needed, preferably with try-with-resources. Closing a connection closes any still-open child handles first.

The driver is synchronous. Queries return streaming handles for multi-table results and table handles for single-table results. Arrow bindings and vector embedder registration are available directly on the connection and, for Arrow input, inside explicit transactions.

  • Method Details

    • open

      public static Velr open()
      Open an in-memory Velr database.
      Returns:
      an open Velr connection

    • open

      public static Velr open(String path)
      Open a Velr database.

      Pass null to open an in-memory database. Passing a path opens or creates the database file at that location.

      Parameters:
      path - database path, or null for an in-memory database
      Returns:
      an open Velr connection

    • openReadonly

      public static Velr openReadonly(String path)
      Open an existing Velr database in read-only mode.
      Parameters:
      path - database path
      Returns:
      an open read-only Velr connection

    • isClosed

      public boolean isClosed()
      Return whether this connection has been closed.
      Returns:
      true after close() has completed

    • schemaVersion

      public int schemaVersion()
      Return the schema version stored in the database file.
      Returns:
      the database schema version

    • currentSchemaVersion

      public int currentSchemaVersion()
      Return the schema version supported by the bundled Velr runtime.
      Returns:
      the current Velr schema version

    • needsMigration

      public boolean needsMigration()
      Return whether the database should be migrated before normal use.
      Returns:
      true when migrate() has work to perform

    • migrate

      public MigrationReport migrate()
      Migrate the database schema to the version supported by the bundled Velr runtime.
      Returns:
      a report describing the migration status and applied steps

    • exec

      public Stream exec(String cypher)
      Execute an openCypher statement and stream every result table it produces.

      Use this method for statements that may produce multiple tables. Close the returned stream when finished, or use try-with-resources.

      Parameters:
      cypher - openCypher statement
      Returns:
      a stream of result tables

    • exec

      public Stream exec(String cypher, QueryOptions options)
      Execute an openCypher statement with query options and stream every result table it produces.
      Parameters:
      cypher - openCypher statement
      options - query options such as parameters and row limits
      Returns:
      a stream of result tables

    • execOne

      public Table execOne(String cypher)
      Execute an openCypher statement that is expected to produce exactly one result table.

      Use exec(String) when a statement may produce multiple tables. Close the returned table when finished, or use try-with-resources.

      Parameters:
      cypher - openCypher statement
      Returns:
      the single result table

    • execOne

      public Table execOne(String cypher, QueryOptions options)
      Execute an openCypher statement with query options that is expected to produce exactly one result table.
      Parameters:
      cypher - openCypher statement
      options - query options such as parameters and row limits
      Returns:
      the single result table

    • run

      public void run(String cypher)
      Execute an openCypher statement and discard any result tables.
      Parameters:
      cypher - openCypher statement

    • run

      public void run(String cypher, QueryOptions options)
      Execute an openCypher statement with query options and discard any result tables.
      Parameters:
      cypher - openCypher statement
      options - query options such as parameters and row limits

    • query

      public List<Map<String,Object>> query(String cypher)
      Execute an openCypher statement and collect the single result table as object maps.

      Column names become map keys. Values are the Java-native rendering returned by Cell.asObject().

      Parameters:
      cypher - openCypher statement
      Returns:
      collected rows

    • query

      public List<Map<String,Object>> query(String cypher, QueryOptions options)
      Execute an openCypher statement with query options and collect the single result table as object maps.
      Parameters:
      cypher - openCypher statement
      options - query options such as parameters and row limits
      Returns:
      collected rows

    • beginTx

      public VelrTx beginTx()
      Begin an explicit transaction.

      Commit or roll back the returned transaction. Closing a transaction without committing or rolling back closes the native transaction handle without committing.

      Returns:
      an open transaction

    • transaction

      public <T> T transaction(TransactionCallback<T> callback) throws Exception
      Run a callback inside a transaction.

      The transaction is committed when the callback returns normally and the transaction is still open. If the callback throws, or if commit is not reached, the transaction is rolled back when it is still open.

      Type Parameters:
      T - callback result type
      Parameters:
      callback - transaction callback
      Returns:
      the callback result
      Throws:
      Exception - if the callback or commit/rollback logic throws

    • explain

      public ExplainTrace explain(String cypher)
      Build an execution plan for an openCypher statement.
      Parameters:
      cypher - openCypher statement
      Returns:
      an explain trace

    • explainAnalyze

      public ExplainTrace explainAnalyze(String cypher)
      Execute and profile an openCypher statement, returning the resulting explain trace.
      Parameters:
      cypher - openCypher statement
      Returns:
      an explain-analyze trace

    • bindArrowIpc

      public void bindArrowIpc(String logical, byte[] ipcBytes)
      Bind Arrow IPC file / Feather v2 bytes as a logical table.

      The byte array is borrowed only for the duration of the call. Velr decodes the IPC file and owns the resulting Arrow arrays before this method returns. Arrow IPC stream bytes are not accepted by this method.

      Parameters:
      logical - logical table name to expose to queries
      ipcBytes - Arrow IPC file / Feather v2 bytes

    • bindArrow

      public void bindArrow(String logical, List<ArrowColumn> columns)
      Bind single-chunk Arrow C Data Interface columns as a logical table.

      For each column, the ArrowArray address is transferred to Velr by this call. Do not use or release transferred arrays after calling this method. The ArrowSchema address is not consumed and may be released after this method returns.

      Parameters:
      logical - logical table name to expose to queries
      columns - one or more Arrow columns

    • bindArrow

      public void bindArrow(String logical, ArrowColumn... columns)
      Bind single-chunk Arrow C Data Interface columns as a logical table.
      Parameters:
      logical - logical table name to expose to queries
      columns - one or more Arrow columns

    • bindArrowChunks

      public void bindArrowChunks(String logical, List<ArrowColumn> columns)
      Bind chunked Arrow C Data Interface columns as a logical table.

      Each column may contain one or more chunks. For every chunk, the ArrowArray address is transferred to Velr by this call. Do not use or release transferred arrays after calling this method. The ArrowSchema address is not consumed and may be released after this method returns.

      Parameters:
      logical - logical table name to expose to queries
      columns - one or more Arrow columns

    • bindArrowChunks

      public void bindArrowChunks(String logical, ArrowColumn... columns)
      Bind chunked Arrow C Data Interface columns as a logical table.
      Parameters:
      logical - logical table name to expose to queries
      columns - one or more Arrow columns

    • registerVectorEmbedder

      public void registerVectorEmbedder(String name, VectorEmbedder embedder)
      Register a named vector embedding callback.

      Reference the same name from CREATE VECTOR INDEX ... OPTIONS { indexConfig: { embedder: 'name' } }. Velr calls the embedder when indexed source values change and when vector queries need query text to be embedded.

      Parameters:
      name - embedder name used by vector index options
      embedder - callback that returns one vector per input

    • close

      public void close()
      Close this connection and any still-open child handles.
      Specified by:
      close in interface AutoCloseable

    • registerChild

      public void registerChild(ai.velr.ChildHandle child)
      Driver-internal child-handle registration hook.

    • unregisterChild

      public void unregisterChild(ai.velr.ChildHandle child)
      Driver-internal child-handle registration hook.