Package com.basis.api.admin

Interface BBjAdminAI

All Superinterfaces:
Remote, Serializable
public interface BBjAdminAI extends Serializable, Remote

Provides access to the Basis AI natural-language-to-SQL library from within the BBj Admin API. Use this interface to configure an LLM provider, index a BBj database schema, and convert plain-English questions into SQL SELECT statements.

Obtain an instance via BBjAdminBase.getAI(). The instance is not yet configured on creation; call configure(BBjAdminAIConfig), loadDefaultConfig(), or loadConfig(String) before invoking any schema or query methods.

Java Sample

BBjAdminBase api = BBjAdminFactory.getBBjAdmin(InetAddress.getByName("myserver"), 2002, true, "admin", "secret");
BBjAdminAI ai = api.getAI();

BBjAdminAIConfig cfg = new BBjAdminAIConfig();
cfg.setActiveProvider(BBjAdminAIConfig.PROVIDER_OPENAI);
cfg.getOpenai().setApiKey("sk-...");
ai.configure(cfg);

ai.indexSchema("jdbc:bbj:///mydb", "admin", "secret", null);
BBjAdminAIQueryResult result = ai.buildQuery("Show all invoices for customer ACME Corp");
if (result.isSuccessful()) {
    System.out.println(result.getGeneratedSql());
}
ai.close();

BBj Sample

use com.basis.api.admin.BBjAdminAI
use com.basis.api.admin.BBjAdminAIConfig
...
ai! = api!.getAI()
cfg! = new BBjAdminAIConfig()
cfg!.setActiveProvider(BBjAdminAIConfig.PROVIDER_OPENAI)
cfg!.getOpenai().setApiKey("sk-...")
ai!.configure(cfg!)
ai!.indexSchema("jdbc:bbj:///mydb", "admin", "secret", BBjAPI.NULL)
result! = ai!.buildQuery("Show all invoices for customer ACME Corp")
if result!.isSuccessful()
  print result!.getGeneratedSql()
endif
ai!.close()
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    BBjAdminAIQueryResult
    buildQuery(String p_naturalLanguageQuery)
    Converts a plain-English question into a SQL SELECT statement using a Retrieval-Augmented Generation (RAG) pipeline.
    void
    clearSchemaIndex()
    Deletes all documents from the schema vector index.
    void
    close()
    Closes the underlying AI engine and releases all resources (schema vector store, embedding model, etc.).
    void
    configure(BBjAdminAIConfig p_config)
    Configures the AI instance with the supplied settings and activates the specified LLM provider.
    BBjAdminAIConfig
    getConfig()
    Returns a snapshot of the currently active configuration, or null if no configuration has been set yet.
    long
    getSchemaDocumentCount()
    Returns the number of documents currently stored in the schema index.
    void
    indexSchema(String p_jdbcUrl, String p_username, String p_password, List<String> p_tables)
    Opens a new JDBC connection, reads the database schema via DatabaseMetaData, embeds the schema as dense vectors, and stores them in a JSON-backed vector store.
    void
    indexSchema(Connection p_connection, List<String> p_tables)
    Indexes the schema using an already-open Connection.
    List<String>
    listIndexedTableNames(String p_jdbcUrl)
    Returns an alphabetically sorted, immutable list of table names that have been indexed in the schema vector store for the database identified by the given JDBC URL.
    List<BBjAdminAISchemaDocument>
    listSchemaDocuments()
    Returns every document in the schema index, sorted by type (TABLE first, then RELATIONSHIP) then by table name.
    List<String>
    listTables(String p_jdbcUrl, String p_username, String p_password)
    Opens a JDBC connection and returns the names of all user tables visible to the given credentials, without modifying the schema index.
    void
    loadConfig(String p_configPath)
    Loads configuration from the specified JSON file path and activates it.
    void
    loadDefaultConfig()
    Loads configuration from the default location (~/.basis-ai/config.json) and activates it.
    void
    saveConfig()
    Encrypts sensitive fields and writes the current configuration to the default location (~/.basis-ai/config.json).
    void
    saveConfig(BBjAdminAIConfig p_config)
    Updates the active configuration from p_config and writes it to the default location (~/.basis-ai/config.json).
    void
    saveConfig(BBjAdminAIConfig p_config, String p_configPath)
    Updates the active configuration from p_config and writes it to the specified path.
    void
    saveConfig(String p_configPath)
    Encrypts sensitive fields and writes the current configuration to the specified path.
    BBjAdminAIPromptResponse
    sendPrompt(BBjAdminAIPromptRequest p_request)
    Sends a fully configured prompt to the LLM, supporting an explicit system prompt, conversation history, temperature override, and max-token override.
    BBjAdminAIPromptResponse
    sendPrompt(String p_prompt)
    Sends a simple one-shot prompt to the configured LLM using the configured generalSystemPrompt.

  • Method Details

    • configure

      void configure(BBjAdminAIConfig p_config) throws BBjAdminException
      Configures the AI instance with the supplied settings and activates the specified LLM provider. Any previously active configuration is discarded.
      Parameters:
      p_config - Configuration to apply. Must not be null.
      Throws:
      BBjAdminException - if the underlying AI engine cannot be initialised with the given configuration.

    • loadDefaultConfig

      void loadDefaultConfig() throws BBjAdminException
      Loads configuration from the default location (~/.basis-ai/config.json) and activates it. If the file does not exist, a default unconfigured instance is prepared.
      Throws:
      BBjAdminException - if the configuration file cannot be read or the AI engine cannot be initialised.

    • loadConfig

      void loadConfig(String p_configPath) throws BBjAdminException
      Loads configuration from the specified JSON file path and activates it.
      Parameters:
      p_configPath - Filesystem path to a JSON configuration file.
      Throws:
      BBjAdminException - if the file cannot be read or the AI engine cannot be initialised.

    • getConfig

      BBjAdminAIConfig getConfig() throws BBjAdminException
      Returns a snapshot of the currently active configuration, or null if no configuration has been set yet.
      Throws:
      BBjAdminException

    • saveConfig

      void saveConfig() throws BBjAdminException
      Encrypts sensitive fields and writes the current configuration to the default location (~/.basis-ai/config.json). Parent directories are created if they do not exist.
      Throws:
      BBjAdminException - if the configuration cannot be written.

    • saveConfig

      void saveConfig(BBjAdminAIConfig p_config) throws BBjAdminException
      Updates the active configuration from p_config and writes it to the default location (~/.basis-ai/config.json).

      This is the preferred overload when the caller obtained a config via getConfig(), modified it, and wants to persist the changes without reinitialising the AI engine.

      Parameters:
      p_config - The configuration to apply and save.
      Throws:
      BBjAdminException - if the configuration cannot be applied or written.

    • saveConfig

      void saveConfig(BBjAdminAIConfig p_config, String p_configPath) throws BBjAdminException
      Updates the active configuration from p_config and writes it to the specified path.
      Parameters:
      p_config - The configuration to apply and save.
      p_configPath - Filesystem path to write the JSON configuration to.
      Throws:
      BBjAdminException - if the configuration cannot be applied or written.

    • saveConfig

      void saveConfig(String p_configPath) throws BBjAdminException
      Encrypts sensitive fields and writes the current configuration to the specified path.
      Parameters:
      p_configPath - Filesystem path to write the JSON configuration to.
      Throws:
      BBjAdminException - if the configuration cannot be written.

    • listIndexedTableNames

      List<String> listIndexedTableNames(String p_jdbcUrl) throws BBjAdminException
      Returns an alphabetically sorted, immutable list of table names that have been indexed in the schema vector store for the database identified by the given JDBC URL. The database name is extracted from the database query-string parameter of the URL.
      Parameters:
      p_jdbcUrl - JDBC URL containing a database=<name> parameter, e.g. jdbc:basis://localhost?database=ChileCompany&token=...
      Returns:
      sorted list of indexed table names; empty if none are indexed
      Throws:
      BBjAdminException - if the index cannot be read

    • listTables

      List<String> listTables(String p_jdbcUrl, String p_username, String p_password) throws BBjAdminException
      Opens a JDBC connection and returns the names of all user tables visible to the given credentials, without modifying the schema index.

      This is a lightweight alternative to indexSchema(java.lang.String, java.lang.String, java.lang.String, java.util.List<java.lang.String>) intended for populating a table-picker UI before the user decides which tables to index.

      Parameters:
      p_jdbcUrl - JDBC connection URL.
      p_username - Database username. May be null.
      p_password - Database password. May be null.
      Returns:
      Sorted, immutable list of table names.
      Throws:
      BBjAdminException - if the connection or metadata call fails.

    • indexSchema

      void indexSchema(String p_jdbcUrl, String p_username, String p_password, List<String> p_tables) throws BBjAdminException
      Opens a new JDBC connection, reads the database schema via DatabaseMetaData, embeds the schema as dense vectors, and stores them in a JSON-backed vector store. Any previously indexed data for the same tables is replaced.

      Schema indexing is a one-time operation. The schema index persists across JVM restarts; re-index only when the database schema changes.

      Parameters:
      p_jdbcUrl - JDBC connection URL (e.g. jdbc:bbj:///mydb).
      p_username - Database username. May be null.
      p_password - Database password. May be null.
      p_tables - Table names to index. Pass null or an empty list to index all tables in the database.
      Throws:
      BBjAdminException - if indexing fails or no AI instance has been configured yet.

    • indexSchema

      void indexSchema(Connection p_connection, List<String> p_tables) throws BBjAdminException
      Indexes the schema using an already-open Connection. The connection is not closed by this method; the caller retains ownership.
      Parameters:
      p_connection - An open JDBC connection.
      p_tables - Table names to index, or null / empty to index all tables.
      Throws:
      BBjAdminException - if indexing fails or no AI instance has been configured yet.

    • clearSchemaIndex

      void clearSchemaIndex() throws BBjAdminException
      Deletes all documents from the schema vector index. Useful before performing a full re-index.
      Throws:
      BBjAdminException - if the index cannot be cleared.

    • getSchemaDocumentCount

      long getSchemaDocumentCount() throws BBjAdminException
      Returns the number of documents currently stored in the schema index.
      Returns:
      Document count.
      Throws:
      BBjAdminException - if the count cannot be retrieved.

    • listSchemaDocuments

      List<BBjAdminAISchemaDocument> listSchemaDocuments() throws BBjAdminException
      Returns every document in the schema index, sorted by type (TABLE first, then RELATIONSHIP) then by table name. Embedding vectors are not included in the returned objects.
      Returns:
      Immutable list of BBjAdminAISchemaDocument objects.
      Throws:
      BBjAdminException - if the index cannot be read.

    • buildQuery

      BBjAdminAIQueryResult buildQuery(String p_naturalLanguageQuery) throws BBjAdminException
      Converts a plain-English question into a SQL SELECT statement using a Retrieval-Augmented Generation (RAG) pipeline. The schema must have been indexed at least once before calling this method.

      Always check BBjAdminAIQueryResult.isSuccessful() before using BBjAdminAIQueryResult.getGeneratedSql().

      Parameters:
      p_naturalLanguageQuery - Plain-English description of the data to retrieve.
      Returns:
      A BBjAdminAIQueryResult containing the generated SQL or an error message.
      Throws:
      BBjAdminException - if the LLM call fails or no AI instance has been configured yet.

    • sendPrompt

      BBjAdminAIPromptResponse sendPrompt(String p_prompt) throws BBjAdminException
      Sends a simple one-shot prompt to the configured LLM using the configured generalSystemPrompt. Ideal for explanations, summaries, or any non-SQL interaction.
      Parameters:
      p_prompt - The user message to send.
      Returns:
      A BBjAdminAIPromptResponse containing the reply and token-usage information.
      Throws:
      BBjAdminException - if the LLM call fails or no AI instance has been configured yet.

    • sendPrompt

      BBjAdminAIPromptResponse sendPrompt(BBjAdminAIPromptRequest p_request) throws BBjAdminException
      Sends a fully configured prompt to the LLM, supporting an explicit system prompt, conversation history, temperature override, and max-token override.
      Parameters:
      p_request - A BBjAdminAIPromptRequest describing the request.
      Returns:
      A BBjAdminAIPromptResponse containing the reply and token-usage information.
      Throws:
      BBjAdminException - if the LLM call fails or no AI instance has been configured yet.

    • close

      void close() throws BBjAdminException
      Closes the underlying AI engine and releases all resources (schema vector store, embedding model, etc.). After this call, all other methods will throw BBjAdminException until the instance is reconfigured via configure(BBjAdminAIConfig) or loadDefaultConfig().
      Throws:
      BBjAdminException - if resources cannot be released cleanly.