Package org.apache.calcite.avatica

# Interface Meta

All Known Subinterfaces:
  `ProtobufMeta`

All Known Implementing Classes:
  `MetaImpl`

public interface Meta
Command handler for getting various metadata. Should be implemented by each driver.

Also holds other abstract methods that are not related to metadata that each provider must implement. This is not ideal.

## Nested Class Summary

Nested Classes
Modifier and Type
Interface
Description
`static class`
`Meta.ConnectionHandle`
Connection handle.
`static interface`
`Meta.ConnectionProperties`
A pojo containing various client-settable `Connection` properties.
`static final class`
`Meta.CursorFactory`
Information necessary to convert an `Iterable` into a `Cursor`.
`static enum`
`Meta.DatabaseProperty`
Database property.
`static class`
`Meta.ExecuteBatchResult`
Response from a collection of SQL commands or parameter values in a single batch.
`static class`
`Meta.ExecuteResult`
Response from execute.
`static interface`
`Meta.Factory`
Factory to create instances of `Meta`.
`static class`
`Meta.Frame`
A collection of rows.
`static class`
`Meta.MetaResultSet`
Meta data from which a result set can be constructed.
`static class`
`Meta.Pat`
Wrapper to remind API calls that a parameter is a pattern (allows '%' and '_' wildcards, per the JDBC spec) rather than a string to be matched exactly.
`static interface`
`Meta.PrepareCallback`
API to put a result set into a statement, being careful to enforce thread-safety and not to overwrite existing open result sets.
`static class`
`Meta.Signature`
Result of preparing a statement.
`static class`
`Meta.StatementHandle`
Statement handle.
`static enum`
`Meta.StatementType`
Type of statement.
`static enum`
`Meta.Style`
How logical fields are represented in the objects returned by the iterator.

## Method Summary

Modifier and Type
Method
Description
`void`
`closeConnection(Meta.ConnectionHandle ch)`
Closes a connection
`void`
`closeStatement(Meta.StatementHandle h)`
Closes a statement.
`void`
`commit(Meta.ConnectionHandle ch)`
Makes all changes since the last commit/rollback permanent.
`Meta.ConnectionProperties`
`connectionSync(Meta.ConnectionHandle ch, Meta.ConnectionProperties connProps)`
Synchronizes client and server view of connection properties.
`Iterable<Object>`
`createIterable(Meta.StatementHandle stmt, QueryState state, Meta.Signature signature, List<TypedValue> parameters, Meta.Frame firstFrame)`
Creates an iterable for a result set.
`Meta.StatementHandle`
`createStatement(Meta.ConnectionHandle ch)`
Called during the creation of a statement to allocate a new handle.
`Meta.ExecuteResult`
`execute(Meta.StatementHandle h, List<TypedValue> parameterValues, int maxRowsInFirstFrame)`
Executes a prepared statement.
`Meta.ExecuteResult`
`execute(Meta.StatementHandle h, List<TypedValue> parameterValues, long maxRowCount)`
Deprecated.
See `execute(StatementHandle, List, int)`
`Meta.ExecuteBatchResult`
`executeBatch(Meta.StatementHandle h, List<List<TypedValue>> parameterValues)`
Executes a collection of bound parameter values on a prepared statement.
`Meta.Frame`
`fetch(Meta.StatementHandle h, long offset, int fetchMaxRowCount)`
Returns a frame of rows.
`Meta.MetaResultSet`
`getAttributes(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat typeNamePattern, Meta.Pat attributeNamePattern)`
Per `DatabaseMetaData.getAttributes(String, String, String, String)`.
`Meta.MetaResultSet`
`getBestRowIdentifier(Meta.ConnectionHandle ch, String catalog, String schema, String table, int scope, boolean nullable)`
Per `DatabaseMetaData.getBestRowIdentifier(String, String, String, int, boolean)`.
`Meta.MetaResultSet`
`getCatalogs(Meta.ConnectionHandle ch)`
Per `DatabaseMetaData.getCatalogs()`.
`Meta.MetaResultSet`
`getClientInfoProperties(Meta.ConnectionHandle ch)`
Per `DatabaseMetaData.getClientInfoProperties()`.
`Meta.MetaResultSet`
`getColumnPrivileges(Meta.ConnectionHandle ch, String catalog, String schema, String table, Meta.Pat columnNamePattern)`
Per `DatabaseMetaData.getColumnPrivileges(String, String, String, String)`.
`Meta.MetaResultSet`
`getColumns(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat tableNamePattern, Meta.Pat columnNamePattern)`
Per `DatabaseMetaData.getColumns(String, String, String, String)`.
`Meta.MetaResultSet`
`getCrossReference(Meta.ConnectionHandle ch, String parentCatalog, String parentSchema, String parentTable, String foreignCatalog, String foreignSchema, String foreignTable)`
Per `DatabaseMetaData.getCrossReference(String, String, String, String, String, String)`.
`Map<Meta.DatabaseProperty,Object>`
`getDatabaseProperties(Meta.ConnectionHandle ch)`
Returns a map of static database properties.
`Meta.MetaResultSet`
`getExportedKeys(Meta.ConnectionHandle ch, String catalog, String schema, String table)`
Per `DatabaseMetaData.getExportedKeys(String, String, String)`.
`Meta.MetaResultSet`
`getFunctionColumns(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat functionNamePattern, Meta.Pat columnNamePattern)`
Per `DatabaseMetaData.getFunctionColumns(String, String, String, String)`.
`Meta.MetaResultSet`
`getFunctions(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat functionNamePattern)`
Per `DatabaseMetaData.getFunctions(String, String, String)`.
`Meta.MetaResultSet`
`getImportedKeys(Meta.ConnectionHandle ch, String catalog, String schema, String table)`
Per `DatabaseMetaData.getImportedKeys(String, String, String)`.
`Meta.MetaResultSet`
`getIndexInfo(Meta.ConnectionHandle ch, String catalog, String schema, String table, boolean unique, boolean approximate)`
Per `DatabaseMetaData.getIndexInfo(String, String, String, boolean, boolean)`.
`Meta.MetaResultSet`
`getPrimaryKeys(Meta.ConnectionHandle ch, String catalog, String schema, String table)`
Per `DatabaseMetaData.getPrimaryKeys(String, String, String)`.
`Meta.MetaResultSet`
`getProcedureColumns(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat procedureNamePattern, Meta.Pat columnNamePattern)`
Per `DatabaseMetaData.getProcedureColumns(String, String, String, String)`.
`Meta.MetaResultSet`
`getProcedures(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat procedureNamePattern)`
Per `DatabaseMetaData.getProcedures(String, String, String)`.
`Meta.MetaResultSet`
`getPseudoColumns(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat tableNamePattern, Meta.Pat columnNamePattern)`
Per `DatabaseMetaData.getPseudoColumns(String, String, String, String)`.
`Meta.MetaResultSet`
`getSchemas(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern)`
`Meta.MetaResultSet`
`getSuperTables(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat tableNamePattern)`
Per `DatabaseMetaData.getSuperTables(String, String, String)`.
`Meta.MetaResultSet`
`getSuperTypes(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat typeNamePattern)`
Per `DatabaseMetaData.getSuperTypes(String, String, String)`.
`Meta.MetaResultSet`
`getTablePrivileges(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat tableNamePattern)`
Per `DatabaseMetaData.getTablePrivileges(String, String, String)`.
`Meta.MetaResultSet`
`getTables(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat tableNamePattern, List<String> typeList)`
Per `DatabaseMetaData.getTables(String, String, String, String[])`.
`Meta.MetaResultSet`
`getTableTypes(Meta.ConnectionHandle ch)`
Per `DatabaseMetaData.getTableTypes()`.
`Meta.MetaResultSet`
`getTypeInfo(Meta.ConnectionHandle ch)`
Per `DatabaseMetaData.getTypeInfo()`.
`Meta.MetaResultSet`
`getUDTs(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat typeNamePattern, int[] types)`
Per `DatabaseMetaData.getUDTs(String, String, String, int[])`.
`Meta.MetaResultSet`
`getVersionColumns(Meta.ConnectionHandle ch, String catalog, String schema, String table)`
Per `DatabaseMetaData.getVersionColumns(String, String, String)`.
`void`
`openConnection(Meta.ConnectionHandle ch, Map<String,String> info)`
Opens (creates) a connection.
`Meta.StatementHandle`
`prepare(Meta.ConnectionHandle ch, String sql, long maxRowCount)`
Prepares a statement.
`Meta.ExecuteResult`
`prepareAndExecute(Meta.StatementHandle h, String sql, long maxRowCount, int maxRowsInFirstFrame, Meta.PrepareCallback callback)`
Prepares and executes a statement.
`Meta.ExecuteResult`
`prepareAndExecute(Meta.StatementHandle h, String sql, long maxRowCount, Meta.PrepareCallback callback)`
Deprecated.
See `prepareAndExecute(StatementHandle, String, long, int, PrepareCallback)`
`Meta.ExecuteBatchResult`
`prepareAndExecuteBatch(Meta.StatementHandle h, List<String> sqlCommands)`
Prepares a statement and then executes a number of SQL commands in one pass.
`void`
`rollback(Meta.ConnectionHandle ch)`
Undoes all changes since the last commit/rollback.
`boolean`
`syncResults(Meta.StatementHandle sh, QueryState state, long offset)`
Re-sets the `ResultSet` on a Statement.

## Method Details

### getDatabaseProperties

Map<Meta.DatabaseProperty,Object> getDatabaseProperties(Meta.ConnectionHandle ch)
Returns a map of static database properties.

The provider can omit properties whose value is the same as the default.

### getTables

Meta.MetaResultSet getTables(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat tableNamePattern, List<String> typeList)
Per `DatabaseMetaData.getTables(String, String, String, String[])`.

### getColumns

Meta.MetaResultSet getColumns(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat tableNamePattern, Meta.Pat columnNamePattern)
Per `DatabaseMetaData.getColumns(String, String, String, String)`.

### getSchemas

Meta.MetaResultSet getSchemas(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern)

### getCatalogs

Meta.MetaResultSet getCatalogs(Meta.ConnectionHandle ch)
Per `DatabaseMetaData.getCatalogs()`.

### getTableTypes

Meta.MetaResultSet getTableTypes(Meta.ConnectionHandle ch)
Per `DatabaseMetaData.getTableTypes()`.

### getProcedures

Meta.MetaResultSet getProcedures(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat procedureNamePattern)
Per `DatabaseMetaData.getProcedures(String, String, String)`.

### getProcedureColumns

Meta.MetaResultSet getProcedureColumns(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat procedureNamePattern, Meta.Pat columnNamePattern)
Per `DatabaseMetaData.getProcedureColumns(String, String, String, String)`.

### getColumnPrivileges

Meta.MetaResultSet getColumnPrivileges(Meta.ConnectionHandle ch, String catalog, String schema, String table, Meta.Pat columnNamePattern)
Per `DatabaseMetaData.getColumnPrivileges(String, String, String, String)`.

### getTablePrivileges

Meta.MetaResultSet getTablePrivileges(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat tableNamePattern)
Per `DatabaseMetaData.getTablePrivileges(String, String, String)`.

### getBestRowIdentifier

Meta.MetaResultSet getBestRowIdentifier(Meta.ConnectionHandle ch, String catalog, String schema, String table, int scope, boolean nullable)
Per `DatabaseMetaData.getBestRowIdentifier(String, String, String, int, boolean)`.

### getVersionColumns

Meta.MetaResultSet getVersionColumns(Meta.ConnectionHandle ch, String catalog, String schema, String table)
Per `DatabaseMetaData.getVersionColumns(String, String, String)`.

### getPrimaryKeys

Meta.MetaResultSet getPrimaryKeys(Meta.ConnectionHandle ch, String catalog, String schema, String table)
Per `DatabaseMetaData.getPrimaryKeys(String, String, String)`.

### getImportedKeys

Meta.MetaResultSet getImportedKeys(Meta.ConnectionHandle ch, String catalog, String schema, String table)
Per `DatabaseMetaData.getImportedKeys(String, String, String)`.

### getExportedKeys

Meta.MetaResultSet getExportedKeys(Meta.ConnectionHandle ch, String catalog, String schema, String table)
Per `DatabaseMetaData.getExportedKeys(String, String, String)`.

### getCrossReference

Meta.MetaResultSet getCrossReference(Meta.ConnectionHandle ch, String parentCatalog, String parentSchema, String parentTable, String foreignCatalog, String foreignSchema, String foreignTable)
Per `DatabaseMetaData.getCrossReference(String, String, String, String, String, String)`.

### getTypeInfo

Meta.MetaResultSet getTypeInfo(Meta.ConnectionHandle ch)
Per `DatabaseMetaData.getTypeInfo()`.

### getIndexInfo

Meta.MetaResultSet getIndexInfo(Meta.ConnectionHandle ch, String catalog, String schema, String table, boolean unique, boolean approximate)
Per `DatabaseMetaData.getIndexInfo(String, String, String, boolean, boolean)`.

### getUDTs

Meta.MetaResultSet getUDTs(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat typeNamePattern, int[] types)
Per `DatabaseMetaData.getUDTs(String, String, String, int[])`.

### getSuperTypes

Meta.MetaResultSet getSuperTypes(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat typeNamePattern)
Per `DatabaseMetaData.getSuperTypes(String, String, String)`.

### getSuperTables

Meta.MetaResultSet getSuperTables(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat tableNamePattern)
Per `DatabaseMetaData.getSuperTables(String, String, String)`.

### getAttributes

Meta.MetaResultSet getAttributes(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat typeNamePattern, Meta.Pat attributeNamePattern)
Per `DatabaseMetaData.getAttributes(String, String, String, String)`.

### getClientInfoProperties

Meta.MetaResultSet getClientInfoProperties(Meta.ConnectionHandle ch)
Per `DatabaseMetaData.getClientInfoProperties()`.

### getFunctions

Meta.MetaResultSet getFunctions(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat functionNamePattern)
Per `DatabaseMetaData.getFunctions(String, String, String)`.

### getFunctionColumns

Meta.MetaResultSet getFunctionColumns(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat functionNamePattern, Meta.Pat columnNamePattern)
Per `DatabaseMetaData.getFunctionColumns(String, String, String, String)`.

### getPseudoColumns

Meta.MetaResultSet getPseudoColumns(Meta.ConnectionHandle ch, String catalog, Meta.Pat schemaPattern, Meta.Pat tableNamePattern, Meta.Pat columnNamePattern)
Per `DatabaseMetaData.getPseudoColumns(String, String, String, String)`.

### createIterable

Iterable<Object> createIterable(Meta.StatementHandle stmt, QueryState state, Meta.Signature signature, List<TypedValue> parameters, Meta.Frame firstFrame)
Creates an iterable for a result set.

The default implementation just returns `iterable`, which it requires to be not null; derived classes may instead choose to execute the relational expression in `signature`.

### prepare

Meta.StatementHandle prepare(Meta.ConnectionHandle ch, String sql, long maxRowCount)
Prepares a statement.

Parameters:
  `ch` - Connection handle
  `sql` - SQL query
  `maxRowCount` - Negative for no limit (different meaning than JDBC)
Returns:
  Signature of prepared statement

### prepareAndExecute

@Deprecated Meta.ExecuteResult prepareAndExecute(Meta.StatementHandle h, String sql, long maxRowCount, Meta.PrepareCallback callback) throws NoSuchStatementException
Deprecated.
See `prepareAndExecute(StatementHandle, String, long, int, PrepareCallback)`
Prepares and executes a statement.

Parameters:
  `h` - Statement handle
  `sql` - SQL query
  `maxRowCount` - Negative for no limit (different meaning than JDBC)
  `callback` - Callback to lock, clear and assign cursor
Returns:
  Result containing statement ID, and if a query, a result set and first frame of data
Throws:
  `NoSuchStatementException`

### prepareAndExecute

Meta.ExecuteResult prepareAndExecute(Meta.StatementHandle h, String sql, long maxRowCount, int maxRowsInFirstFrame, Meta.PrepareCallback callback) throws NoSuchStatementException
Prepares and executes a statement.

Parameters:
  `h` - Statement handle
  `sql` - SQL query
  `maxRowCount` - Maximum number of rows for the entire query. Negative for no limit (different meaning than JDBC).
  `maxRowsInFirstFrame` - Maximum number of rows for the first frame. This value should always be less than or equal to `maxRowCount` as the number of results are guaranteed to be restricted by `maxRowCount` and the underlying database.
  `callback` - Callback to lock, clear and assign cursor
Returns:
  Result containing statement ID, and if a query, a result set and first frame of data
Throws:
  `NoSuchStatementException`

### prepareAndExecuteBatch

Meta.ExecuteBatchResult prepareAndExecuteBatch(Meta.StatementHandle h, List<String> sqlCommands) throws NoSuchStatementException
Prepares a statement and then executes a number of SQL commands in one pass.

Parameters:
  `h` - Statement handle
  `sqlCommands` - SQL commands to run
Returns:
  An array of update counts containing one element for each command in the batch.
Throws:
  `NoSuchStatementException`

### executeBatch

Meta.ExecuteBatchResult executeBatch(Meta.StatementHandle h, List<List<TypedValue>> parameterValues) throws NoSuchStatementException
Executes a collection of bound parameter values on a prepared statement.

Parameters:
  `h` - Statement handle
  `parameterValues` - A collection of list of typed values, one list per batch
Returns:
  An array of update counts containing one element for each command in the batch.
Throws:
  `NoSuchStatementException`

### fetch

Meta.Frame fetch(Meta.StatementHandle h, long offset, int fetchMaxRowCount) throws NoSuchStatementException, MissingResultsException
Returns a frame of rows.

The frame describes whether there may be another frame. If there is not another frame, the current iteration is done when we have finished the rows in the this frame.

The default implementation always returns null.

Parameters:
  `h` - Statement handle
  `offset` - Zero-based offset of first row in the requested frame
  `fetchMaxRowCount` - Maximum number of rows to return; negative means no limit
Returns:
  Frame, or null if there are no more
Throws:
  `NoSuchStatementException`
  `MissingResultsException`

### execute

@Deprecated Meta.ExecuteResult execute(Meta.StatementHandle h, List<TypedValue> parameterValues, long maxRowCount) throws NoSuchStatementException
Deprecated.
See `execute(StatementHandle, List, int)`
Executes a prepared statement.

Parameters:
  `h` - Statement handle
  `parameterValues` - A list of parameter values; may be empty, not null
  `maxRowCount` - Maximum number of rows to return; negative means no limit
Returns:
  Execute result
Throws:
  `NoSuchStatementException`

### execute

Meta.ExecuteResult execute(Meta.StatementHandle h, List<TypedValue> parameterValues, int maxRowsInFirstFrame) throws NoSuchStatementException
Executes a prepared statement.

Parameters:
  `h` - Statement handle
  `parameterValues` - A list of parameter values; may be empty, not null
  `maxRowsInFirstFrame` - Maximum number of rows to return in the Frame.
Returns:
  Execute result
Throws:
  `NoSuchStatementException`

### createStatement

Meta.StatementHandle createStatement(Meta.ConnectionHandle ch)
Called during the creation of a statement to allocate a new handle.

Parameters:
  `ch` - Connection handle

### closeStatement

void closeStatement(Meta.StatementHandle h)
Closes a statement.

If the statement handle is not known, or is already closed, does nothing.

Parameters:
  `h` - Statement handle

### openConnection

void openConnection(Meta.ConnectionHandle ch, Map<String,String> info)
Opens (creates) a connection. The client allocates its own connection ID which the server is then made aware of through the `Meta.ConnectionHandle`. The Map `info` argument is analogous to the `Properties` typically passed to a "normal" JDBC Driver. Avatica specific properties should not be included -- only properties for the underlying driver.

Parameters:
  `ch` - A ConnectionHandle encapsulates information about the connection to be opened as provided by the client.
  `info` - A Map corresponding to the Properties typically passed to a JDBC Driver.

### closeConnection

void closeConnection(Meta.ConnectionHandle ch)
Closes a connection

### syncResults

boolean syncResults(Meta.StatementHandle sh, QueryState state, long offset) throws NoSuchStatementException
Re-sets the `ResultSet` on a Statement. Not a JDBC method.

Returns:
  True if there are results to fetch after resetting to the given offset. False otherwise
Throws:
  `NoSuchStatementException`

### commit

void commit(Meta.ConnectionHandle ch)
Makes all changes since the last commit/rollback permanent. Analogous to `Connection.commit()`.

Parameters:
  `ch` - A reference to the real JDBC Connection

### rollback

void rollback(Meta.ConnectionHandle ch)
Undoes all changes since the last commit/rollback. Analogous to `Connection.rollback()`;

Parameters:
  `ch` - A reference to the real JDBC Connection

### connectionSync

Meta.ConnectionProperties connectionSync(Meta.ConnectionHandle ch, Meta.ConnectionProperties connProps)
Synchronizes client and server view of connection properties.

Note: this interface is considered "experimental" and may undergo further changes as this functionality is extended to other aspects of state management for `Connection`, `Statement`, and `ResultSet`.