Package com.complexible.stardog.virtual.api.admin

# Interface VirtualGraphAdminConnection

All Superinterfaces:
  `AdminConnection`, `AutoCloseable`

public interface VirtualGraphAdminConnection extends AdminConnection
Connection to manage data sources and virtual graphs

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static enum`
  `VirtualGraphAdminConnection.InputFileType`

  ## Nested classes/interfaces inherited from interface com.complexible.stardog.api.admin.AdminConnection

  `AdminConnection.StreamConsumer, AdminConnection.TxLogRange`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ALL_DBS`
  `static final String`
  `ALL_NAMED_GRAPHS`

  ### Fields inherited from interface com.complexible.stardog.api.admin.AdminConnection

  `NO_TIMEOUT`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addDataSource(String theName, Properties theOptions)`
  Add a data source with the given properties
  `void`
  `addGraph(String theName, String theDataSource, String theDatabase, Properties theOptions, Iterable<Statement> theMappings)`
  Registers a new virtual graph against a named data source
  `default void`
  `addGraph(String theName, String theDataSource, String theDatabase, Properties theOptions, String theMappings)`
  Registers a new virtual graph using a data source.
  `void`
  `addGraph(String theName, String theDatabase, Properties theOptions, Iterable<Statement> theMappings)`
  Registers a new virtual graph.
  `void`
  `addGraph(String theName, String theDatabase, Properties theOptions, String theMappings)`
  Deprecated.
  Use `addGraph(String, String, String, Properties, String)` with null dataSource
  `void`
  `addGraph(String theName, String theDataSourceName, Set<Statement> theMetadata, String theDatabase, Properties theOptions, String theMappings)`
  Deprecated.
  For Stardog internal use only
  `default void`
  `addGraph(String theName, Properties theOptions, Iterable<Statement> theMappings)`
  Registers a new virtual graph to be associated with all databases.
  `default void`
  `addGraph(String theName, Properties theOptions, String theMappings)`
  Registers a new virtual graph for access from all databases
  `DataSourceInfo`
  `getDataSourceInfo(String theName)`
  Retrieve the data source details for the named data source
  `default DataSourceInfo`
  `getDataSourceInfoOrNull(String theName)`
  Retrieve the data source details for the named data source or null if it doesn't exist
  `Collection<DataSourceInfo>`
  `getDataSourceInfos()`
  Returns information on all registered data sources.
  `Set<Statement>`
  `getDataSourceMetadata(String theName)`
  Retrieve all the metadata that a DataSource has cached for its connection.
  `Properties`
  `getDataSourceOptions(String theName)`
  Get the data source options
  `com.google.gson.JsonArray`
  `getDataSourceTables(String dsName)`
  Retrieve all the tables that a DataSource has access to.
  `String`
  `getDbTypeOptionsDescription()`
  Describes options for configuring data sources and virtual graphs.
  `VirtualGraph`
  `getGraph(String theName)`
  Deprecated.
  Use getVirtualGraphInfo or the other methods
  `default String`
  `getMappings(String vgName)`
  Get mappings for the named virtual graph in R2RML format
  `String`
  `getMappingsString(String theName, String theSyntax)`
  Get the serialized mappings
  `Set<Statement>`
  `getMatchingSuggestions(Set<Statement> theInput)`
  Aligns data source and targets based on their lexical, data type, word sense similarity and returns those alignments as statements
  `Properties`
  `getOptions(String theName)`
  Get the virtual graph options
  `com.google.gson.JsonObject`
  `getTableMetadataJson(String dsName, String catalog, String schema, String tableName, String tableType)`
  Retrieve the datasource metadata for only the table provided.
  `Set<Statement>`
  `getTableMetadataRdf(String dsName, String catalog, String schema, String tableName, String tableType)`
  Retrieve the datasource metadata for only the table provided.
  `VirtualGraphInfo`
  `getVirtualGraphInfo(String theName)`
  Return a `VirtualGraphInfo` for the supplied graph
  `VirtualGraphInfo`
  `getVirtualGraphInfoOrNull(String theName)`
  Return a `VirtualGraphInfo` for the supplied graph or null if it does not exist
  `Collection<VirtualGraphInfo>`
  `getVirtualGraphInfos()`
  Returns information on all registered virtual graphs.
  `void`
  `importFile(String theMappings, Properties theOptions, String theDb, IRI theNg, File theFile, VirtualGraphAdminConnection.InputFileType theFormat)`
  Import a file (CSV/JSON) in a single transaction.
  `void`
  `importFile(String theMappings, Properties theOptions, String theDb, IRI theNg, InputStream theData, String thePathFileName, IRI theFileIri, VirtualGraphAdminConnection.InputFileType theFormat)`
  Import a stream (CSV/JSON) in a single transaction
  `void`
  `importGraph(String theDatabase, String theDataSource, Properties theOptions, String theMappings, String theNamedGraph, boolean theRemoveAll)`
  Import a DB by copy/add a temporary VG.
  `default void`
  `importGraph(String theDatabase, Properties theOptions, String theMappings, String theNamedGraph, boolean theRemoveAll)`
  Deprecated.
  use `importGraph(String, String, Properties, String, String, boolean)` with a null DataSource
  `void`
  `modifyDataSource(String theName, Properties theOptionUpdates)`
  Update a data source with a set of modifications to its existing options.
  `void`
  `onlineDataSource(String theName)`
  Brings online the registered data source with the given name, as well as its dependent virtual graphs.
  `void`
  `onlineGraph(String theName)`
  Brings online the registered virtual graph with the given name.
  `DataSourceQueryResult`
  `queryDataSource(String theName, String theQuery, String theTimeout, Properties theOptions)`
  Query a DataSource with its native query language.
  `void`
  `refreshCounts(String theDataSourceName, String theTableName)`
  Update the cardinality (row count) estimates for the supplied data source and table.
  `void`
  `refreshMetadata(String theDataSourceName, String theTableName)`
  Refresh the metadata for the supplied data source and table.
  `boolean`
  `removeDataSource(String theName, boolean theForce)`
  Remove a data source, and optionally all virtual graphs associated with it if you use `theForce`
  `boolean`
  `removeGraph(String theName)`
  Removes the registered virtual graph with the given name.
  `void`
  `replaceAllMetadata(String theDataSourceName, Set<Statement> theMetadata, Map<String,Boolean> theVgAvailability)`
  Replace all metadata for a data source.
  `void`
  `replaceDataSourceMetadata(String theName, Collection<Statement> theStatements)`
  Replaces the metadata for a DataSource with the supplied RDF.
  `void`
  `replaceTableMetadata(String theDataSourceName, String theCatalog, String theSchema, String theTableName, String theTableType, Set<Statement> theMetadata, Map<String,Boolean> theVgAvailability)`
  Replace the metadata for a single table in a data source.
  `void`
  `shareDataSource(String theName)`
  Share a private data source so it can be used by other virtual graphs and will endure after its dependent virtual graph is removed.
  `void`
  `testDataSource(String theName)`
  Test an existing data source connection.
  `default void`
  `testNewConnection(Properties theOptions)`
  Test the connection for a new data source.
  `default void`
  `updateDataSource(String theName, Properties theOptions)`
  Update a data source with the given options.
  `default void`
  `updateDataSource(String theName, Properties theOptions, boolean theForce)`
  Update a data source with the given options, refreshing dependent virtual graphs
  `void`
  `updateDataSource(String theName, Set<Statement> theMetadata, Properties theOptions, boolean theForce, boolean theShareable)`
  Deprecated.
  For Stardog internal use only
  `default void`
  `updateGraph(String theName, String theDataSource, String theDatabase, Properties theOptions, String theMappings)`
  Registers a new virtual graph using a data source and overwriting a previous version if it exists.
  `void`
  `updateGraph(String theName, String theDatabase, Properties theOptions, Iterable<Statement> theMappings)`
  Registers a new virtual graph overwriting a previous version if it exists.
  `void`
  `updateGraph(String theName, String theDatabase, Properties theOptions, String theMappings)`
  Deprecated.
  Use `updateGraph(String, String, String, Properties, String)` with null dataSource
  `void`
  `updateGraph(String theName, String theDataSourceName, Set<Statement> theMetadata, String theDatabase, Properties theOptions, String theMappings)`
  Deprecated.
  For Stardog internal use only
  `default void`
  `updateGraph(String theName, Properties theOptions, Iterable<Statement> theMappings)`
  Registers a new virtual graph to be associated with all databases, overwriting a previous version if it exists.
  `default void`
  `updateGraph(String theName, Properties theOptions, String theMappings)`
  Registers a new virtual graph for access from all databases, overwriting a previous version if it exists.

  ### Methods inherited from interface com.complexible.stardog.api.admin.AdminConnection

  `as, backup, backup, backup, backup, backupAll, builder, checkpoint, close, currentStatus, currentStatus, disk, drop, generateDiagnosticReport, get, get, getLogs, getPermissionManager, getProcessManager, getProperty, getQueryManager, getRoleManager, getStoredFunctions, getStoredQueries, getTokenManager, getUserManager, isOpen, list, newDatabase, offline, offline, online, optimize, optimize, renameDatabase, repair, replayTransactionLog, restore, restore, set, setProperty, shutdown, transactionLog, verify, whoami`

- ## Field Details

  - ### ALL_DBS

    static final String ALL_DBS
    See Also:
      - Constant Field Values

  - ### ALL_NAMED_GRAPHS

    static final String ALL_NAMED_GRAPHS
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getVirtualGraphInfos

    Collection<VirtualGraphInfo> getVirtualGraphInfos()
    Returns information on all registered virtual graphs.

  - ### getGraph

    @Deprecated VirtualGraph getGraph(String theName)
    Deprecated.
    Use getVirtualGraphInfo or the other methods
    Returns the registered virtual graph with the given name.
    Throws:
      `StardogException` - if the graph does not exist or there is an error getting the graph

  - ### getVirtualGraphInfo

    VirtualGraphInfo getVirtualGraphInfo(String theName)
    Return a `VirtualGraphInfo` for the supplied graph
    Parameters:
      `theName` - the (local) name of the virtual graph (without the virtual:// prefix)

  - ### getVirtualGraphInfoOrNull

    VirtualGraphInfo getVirtualGraphInfoOrNull(String theName)
    Return a `VirtualGraphInfo` for the supplied graph or null if it does not exist

  - ### getOptions

    Properties getOptions(String theName)
    Get the virtual graph options

  - ### getMappings

    default String getMappings(String vgName)
    Get mappings for the named virtual graph in R2RML format

  - ### getMappingsString

    String getMappingsString(String theName, String theSyntax)
    Get the serialized mappings

  - ### removeGraph

    boolean removeGraph(String theName)
    Removes the registered virtual graph with the given name. return `true` if the virtual graph exists and was removed, `false` if the virtual graph does not exist
    Throws:
      `StardogException` - if there is an error removing the graph

  - ### onlineGraph

    void onlineGraph(String theName)
    Brings online the registered virtual graph with the given name.
    Throws:
      `StardogException` - if there is an error reloading the graph

  - ### addGraph

    default void addGraph(String theName, Properties theOptions, Iterable<Statement> theMappings)
    Registers a new virtual graph to be associated with all databases.
    Throws:
      `StardogException` - if there is already a registered virtual graph with the given name or if there is an error adding the graph

  - ### addGraph

    void addGraph(String theName, String theDatabase, Properties theOptions, Iterable<Statement> theMappings)
    Registers a new virtual graph.
    Throws:
      `StardogException` - if there is already a registered virtual graph with the given name or if there is an error adding the graph

  - ### addGraph

    void addGraph(String theName, String theDataSource, String theDatabase, Properties theOptions, Iterable<Statement> theMappings)
    Registers a new virtual graph against a named data source

  - ### addGraph

    default void addGraph(String theName, Properties theOptions, String theMappings)
    Registers a new virtual graph for access from all databases

  - ### addGraph

    @Deprecated void addGraph(String theName, String theDatabase, Properties theOptions, String theMappings)
    Deprecated.
    Use `addGraph(String, String, String, Properties, String)` with null dataSource
    Registers a new virtual graph. TODO : another arg for mappings format? We can detect from CLI and require it here
    Throws:
      `StardogException` - if there is already a registered virtual graph with the given name or if there is an error adding the graph

  - ### addGraph

    default void addGraph(String theName, String theDataSource, String theDatabase, Properties theOptions, String theMappings)
    Registers a new virtual graph using a data source.
    Throws:
      `StardogException` - if there is already a registered virtual graph with the given name or if there is an error adding the graph

  - ### addGraph

    @Deprecated void addGraph(String theName, @Nullable String theDataSourceName, @Nullable Set<Statement> theMetadata, String theDatabase, Properties theOptions, String theMappings)
    Deprecated.
    For Stardog internal use only
    Registers a new virtual graph using a data source and, if theMetadata is not null, initializing the metadata cache with the supplied statements.
    Throws:
      `StardogException` - if there is already a registered virtual graph with the given name or if there is an error adding the graph

  - ### updateGraph

    default void updateGraph(String theName, Properties theOptions, Iterable<Statement> theMappings)
    Registers a new virtual graph to be associated with all databases, overwriting a previous version if it exists.
    Throws:
      `StardogException` - if there is an error updating the graph

  - ### updateGraph

    void updateGraph(String theName, String theDatabase, Properties theOptions, Iterable<Statement> theMappings)
    Registers a new virtual graph overwriting a previous version if it exists.
    Throws:
      `StardogException` - if there is an error updating the graph

  - ### updateGraph

    default void updateGraph(String theName, Properties theOptions, String theMappings)
    Registers a new virtual graph for access from all databases, overwriting a previous version if it exists.

  - ### updateGraph

    @Deprecated void updateGraph(String theName, String theDatabase, Properties theOptions, String theMappings)
    Deprecated.
    Use `updateGraph(String, String, String, Properties, String)` with null dataSource
    Registers a new virtual graph overwriting a previous version if it exists. TODO : another arg for mappings format? We can detect from CLI and require it here
    Throws:
      `StardogException` - if there is an error updating the graph

  - ### updateGraph

    default void updateGraph(String theName, String theDataSource, String theDatabase, Properties theOptions, String theMappings)
    Registers a new virtual graph using a data source and overwriting a previous version if it exists.
    Throws:
      `StardogException` - if there is an error updating the graph

  - ### updateGraph

    @Deprecated void updateGraph(String theName, @Nullable String theDataSourceName, @Nullable Set<Statement> theMetadata, String theDatabase, Properties theOptions, String theMappings)
    Deprecated.
    For Stardog internal use only
    Registers a new virtual graph using a data source, overwriting a previous version if it exists and, if theMetadata is not null, initializing the metadata cache with the supplied statements.

  - ### importGraph

    @Deprecated default void importGraph(String theDatabase, Properties theOptions, String theMappings, String theNamedGraph, boolean theRemoveAll)
    Deprecated.
    use `importGraph(String, String, Properties, String, String, boolean)` with a null DataSource
    Import a DB by copy/add a temporary VG.

  - ### importGraph

    void importGraph(String theDatabase, @Nullable String theDataSource, Properties theOptions, String theMappings, String theNamedGraph, boolean theRemoveAll)
    Import a DB by copy/add a temporary VG.

  - ### importFile

    void importFile(String theMappings, Properties theOptions, String theDb, IRI theNg, File theFile, VirtualGraphAdminConnection.InputFileType theFormat)
    Import a file (CSV/JSON) in a single transaction. Using a file has the advantage of being a repeatable source when negotiating a Kerberos connection.

  - ### importFile

    void importFile(String theMappings, Properties theOptions, String theDb, IRI theNg, InputStream theData, String thePathFileName, IRI theFileIri, VirtualGraphAdminConnection.InputFileType theFormat)
    Import a stream (CSV/JSON) in a single transaction
    Parameters:
      `theMappings` - optional mappings
      `theOptions` - optional options
      `theDb` - the target database
      `theNg` - the (nullable) target named graph
      `theData` - the InputStream
      `thePathFileName` - the name to give to the stream for catalog metadata purposes
      `theFileIri` - optional IRI of the input stream for catalog metadata purposes
      `theFormat` - the format of the file (DELIMITED/JSON)

  - ### addDataSource

    void addDataSource(String theName, Properties theOptions)
    Add a data source with the given properties

  - ### updateDataSource

    default void updateDataSource(String theName, Properties theOptions)
    Update a data source with the given options.

  - ### updateDataSource

    default void updateDataSource(String theName, Properties theOptions, boolean theForce)
    Update a data source with the given options, refreshing dependent virtual graphs

  - ### updateDataSource

    @Deprecated void updateDataSource(String theName, @Nullable Set<Statement> theMetadata, Properties theOptions, boolean theForce, boolean theShareable)
    Deprecated.
    For Stardog internal use only
    Update a data source with the given options, refreshing dependent virtual graphs. If theMetadata is not null, initializes the metadata cache with the supplied statements.

  - ### modifyDataSource

    void modifyDataSource(String theName, Properties theOptionUpdates)
    Update a data source with a set of modifications to its existing options. Options the already exist in the data source but are not included in the updates will be retained. To remove an option, supply the property with an empty (`""`) value.
    Parameters:
      `theName` - The local name of the data source
      `theOptionUpdates` - The options to add or remove from the existing configuration

  - ### removeDataSource

    boolean removeDataSource(String theName, boolean theForce)
    Remove a data source, and optionally all virtual graphs associated with it if you use `theForce`

  - ### shareDataSource

    void shareDataSource(String theName)
    Share a private data source so it can be used by other virtual graphs and will endure after its dependent virtual graph is removed.
    Parameters:
      `theName` - the (local) name of the data source
    Throws:
      `StardogException` - if the data source is not found or there is an error making the data source sharable

  - ### getDataSourceInfos

    Collection<DataSourceInfo> getDataSourceInfos()
    Returns information on all registered data sources.

  - ### onlineDataSource

    void onlineDataSource(String theName)
    Brings online the registered data source with the given name, as well as its dependent virtual graphs.
    Throws:
      `StardogException` - if there is an error reloading the data source

  - ### testDataSource

    void testDataSource(String theName)
    Test an existing data source connection.
    Throws:
      `StardogException` - if there is an error testing the data source

  - ### testNewConnection

    default void testNewConnection(Properties theOptions)
    Test the connection for a new data source.

  - ### getDataSourceInfo

    DataSourceInfo getDataSourceInfo(String theName)
    Retrieve the data source details for the named data source
    Throws:
      `IllegalArgumentException` - if DataSource is not found

  - ### getDataSourceInfoOrNull

    default DataSourceInfo getDataSourceInfoOrNull(String theName)
    Retrieve the data source details for the named data source or null if it doesn't exist

  - ### getDataSourceOptions

    Properties getDataSourceOptions(String theName)
    Get the data source options

  - ### getDataSourceMetadata

    @Beta Set<Statement> getDataSourceMetadata(String theName)
    Retrieve all the metadata that a DataSource has cached for its connection. NOTE: The schema of the metadata may change with new releases.
    Returns:
      the metadata in RDF format

  - ### getDataSourceTables

    @Beta com.google.gson.JsonArray getDataSourceTables(String dsName)
    Retrieve all the tables that a DataSource has access to.
    Returns:
      Array of Objects containing catalog, schema, table name and table type

  - ### getTableMetadataRdf

    @Beta Set<Statement> getTableMetadataRdf(String dsName, @Nullable String catalog, @Nullable String schema, String tableName, String tableType)
    Retrieve the datasource metadata for only the table provided.
    Returns:
      the metadata in RDF format

  - ### getTableMetadataJson

    @Beta com.google.gson.JsonObject getTableMetadataJson(String dsName, @Nullable String catalog, @Nullable String schema, String tableName, String tableType)
    Retrieve the datasource metadata for only the table provided.
    Returns:
      the metadata in JSON format

  - ### refreshMetadata

    void refreshMetadata(String theDataSourceName, @Nullable String theTableName)
    Refresh the metadata for the supplied data source and table. If `theTableName` is `null`, refresh metadata for all tables that have been loaded through the data source.

    Call this if the schema (column names or data types) has changed for tables accessed by the data source, or if tables were created or dropped since the data source was created or refreshed.

    Parameters:
      `theDataSourceName` - local name of the data source
      `theTableName` - name of the table (eg. myschema.mytable or mytable)
    Throws:
      `IllegalArgumentException` - if table was provided but not found

  - ### replaceTableMetadata

    void replaceTableMetadata(String theDataSourceName, @Nullable String theCatalog, @Nullable String theSchema, String theTableName, String theTableType, Set<Statement> theMetadata, Map<String,Boolean> theVgAvailability)
    Replace the metadata for a single table in a data source. For use in cluster replication.

    If metadata is non-empty: adds or updates the table's metadata. If metadata is empty: removes the table from the cache.

    After metadata is updated, dependent virtual graphs are rebuilt with the specified availability.

    Parameters:
      `theDataSourceName` - local name of the data source
      `theCatalog` - table catalog (nullable)
      `theSchema` - table schema (nullable)
      `theTableName` - table name
      `theTableType` - table type (TABLE, VIEW, etc.)
      `theMetadata` - RDF statements for the table (empty to delete)
      `theVgAvailability` - the expected availability state for dependent VGs after reload

  - ### replaceAllMetadata

    void replaceAllMetadata(String theDataSourceName, Set<Statement> theMetadata, Map<String,Boolean> theVgAvailability)
    Replace all metadata for a data source. For use in cluster replication.

    After metadata is replaced, dependent virtual graphs are rebuilt with the specified availability.

    Parameters:
      `theDataSourceName` - local name of the data source
      `theMetadata` - RDF statements for all tables
      `theVgAvailability` - the expected availability state for dependent VGs after reload

  - ### refreshCounts

    void refreshCounts(String theDataSourceName, @Nullable String theTableName)
    Update the cardinality (row count) estimates for the supplied data source and table. If `theTableName` is `null`, refresh counts for all tables that have been loaded through the data source.
    Parameters:
      `theDataSourceName` - local name of the data source
      `theTableName` - name of the table (eg. myschema.mytable or mytable)
    Throws:
      `IllegalArgumentException` - if table was provided but has not been loaded by a virtual graph

  - ### replaceDataSourceMetadata

    @Beta void replaceDataSourceMetadata(String theName, Collection<Statement> theStatements)
    Replaces the metadata for a DataSource with the supplied RDF. NOTE: The schema of the metadata may change with new releases.

  - ### queryDataSource

    DataSourceQueryResult queryDataSource(String theName, String theQuery, String theTimeout, Properties theOptions)
    Query a DataSource with its native query language.

  - ### getDbTypeOptionsDescription

    String getDbTypeOptionsDescription()
    Describes options for configuring data sources and virtual graphs. Includes DB-type families, available options, data types, defaults and whether required. For use with data-driven UIs such as Studio.
    Returns:
      a JSON option detailing DB types and their options

  - ### getMatchingSuggestions

    Set<Statement> getMatchingSuggestions(Set<Statement> theInput)
    Aligns data source and targets based on their lexical, data type, word sense similarity and returns those alignments as statements
    Parameters:
      `theInput` - data source and target metadata, optionally with unpublished ontology in designer via a named graph
    Returns:
      alignments