Package org.apache.arrow.flight.sql

Class FlightSqlClient

java.lang.Object

org.apache.arrow.flight.sql.FlightSqlClient

All Implemented Interfaces:

AutoCloseable

public class FlightSqlClient
extends Object
implements AutoCloseable

Flight client with Flight SQL semantics.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	FlightSqlClient.PreparedStatement	Helper class to encapsulate Flight SQL prepared statement logic.
static class	FlightSqlClient.Savepoint	A handle for an active savepoint.
static final class	FlightSqlClient.SubstraitPlan	A wrapper around a Substrait plan and a Substrait version.
static class	FlightSqlClient.Transaction	A handle for an active transaction.

Constructor Summary

Constructors

Constructor	Description
FlightSqlClient(FlightClient client)

Method Summary

Modifier and Type	Method	Description
FlightSqlClient.Savepoint	beginSavepoint(FlightSqlClient.Transaction transaction, String name, CallOption... options)	Create a savepoint within a transaction.
FlightSqlClient.Transaction	beginTransaction(CallOption... options)	Begin a transaction.
CancelFlightInfoResult	cancelFlightInfo(CancelFlightInfoRequest request, CallOption... options)	Cancel execution of a distributed query.
CancelResult	cancelQuery(FlightInfo info, CallOption... options)	Deprecated. Prefer cancelFlightInfo(org.apache.arrow.flight.CancelFlightInfoRequest, org.apache.arrow.flight.CallOption...).
void	close()
CloseSessionResult	closeSession(CloseSessionRequest request, CallOption... options)
void	commit(FlightSqlClient.Transaction transaction, CallOption... options)	Commit a transaction.
FlightInfo	execute(String query, CallOption... options)	Execute a query on the server.
FlightInfo	execute(String query, FlightSqlClient.Transaction transaction, CallOption... options)	Execute a query on the server.
FlightInfo	executeSubstrait(FlightSqlClient.SubstraitPlan plan, CallOption... options)	Execute a Substrait plan on the server.
FlightInfo	executeSubstrait(FlightSqlClient.SubstraitPlan plan, FlightSqlClient.Transaction transaction, CallOption... options)	Execute a Substrait plan on the server.
long	executeSubstraitUpdate(FlightSqlClient.SubstraitPlan plan, CallOption... options)	Execute an update query on the server.
long	executeSubstraitUpdate(FlightSqlClient.SubstraitPlan plan, FlightSqlClient.Transaction transaction, CallOption... options)	Execute an update query on the server.
long	executeUpdate(String query, CallOption... options)	Execute an update query on the server.
long	executeUpdate(String query, FlightSqlClient.Transaction transaction, CallOption... options)	Execute an update query on the server.
FlightInfo	getCatalogs(CallOption... options)	Request a list of catalogs.
SchemaResult	getCatalogsSchema(CallOption... options)	Get the schema of getCatalogs(CallOption...) from the server.
FlightInfo	getCrossReference(TableRef pkTableRef, TableRef fkTableRef, CallOption... options)	Retrieves a description of the foreign key columns that reference the given table's primary key columns (the foreign keys exported by a table).
SchemaResult	getCrossReferenceSchema(CallOption... options)	Get the schema of getCrossReference(TableRef, TableRef, CallOption...) from the server.
SchemaResult	getExecuteSchema(String query, CallOption... options)	Get the schema of the result set of a query.
SchemaResult	getExecuteSchema(String query, FlightSqlClient.Transaction transaction, CallOption... options)	Get the schema of the result set of a query.
SchemaResult	getExecuteSubstraitSchema(FlightSqlClient.SubstraitPlan substraitPlan, CallOption... options)	Get the schema of the result set of a Substrait plan.
SchemaResult	getExecuteSubstraitSchema(FlightSqlClient.SubstraitPlan plan, FlightSqlClient.Transaction transaction, CallOption... options)	Get the schema of the result set of a Substrait plan.
FlightInfo	getExportedKeys(TableRef tableRef, CallOption... options)	Retrieves a description about the foreign key columns that reference the primary key columns of the given table.
SchemaResult	getExportedKeysSchema(CallOption... options)	Get the schema of getExportedKeys(TableRef, CallOption...) from the server.
FlightInfo	getImportedKeys(TableRef tableRef, CallOption... options)	Retrieves the foreign key columns for the given table.
SchemaResult	getImportedKeysSchema(CallOption... options)	Get the schema of getImportedKeys(TableRef, CallOption...) from the server.
FlightInfo	getPrimaryKeys(TableRef tableRef, CallOption... options)	Request the primary keys for a table.
SchemaResult	getPrimaryKeysSchema(CallOption... options)	Get the schema of getPrimaryKeys(TableRef, CallOption...) from the server.
SchemaResult	getSchema(FlightDescriptor descriptor, CallOption... options)	Get schema for a stream.
FlightInfo	getSchemas(String catalog, String dbSchemaFilterPattern, CallOption... options)	Request a list of schemas.
SchemaResult	getSchemasSchema(CallOption... options)	Get the schema of getSchemas(String, String, CallOption...) from the server.
GetSessionOptionsResult	getSessionOptions(GetSessionOptionsRequest request, CallOption... options)
FlightInfo	getSqlInfo(int[] info, CallOption... options)	Request a set of Flight SQL metadata.
FlightInfo	getSqlInfo(Iterable<Integer> info, CallOption... options)	Request a set of Flight SQL metadata.
FlightInfo	getSqlInfo(FlightSql.SqlInfo... info)	Request a set of Flight SQL metadata.
FlightInfo	getSqlInfo(FlightSql.SqlInfo[] info, CallOption... options)	Request a set of Flight SQL metadata.
SchemaResult	getSqlInfoSchema(CallOption... options)	Get the schema of getSqlInfo(SqlInfo...) from the server.
FlightStream	getStream(Ticket ticket, CallOption... options)	Retrieve a stream from the server.
FlightInfo	getTables(String catalog, String dbSchemaFilterPattern, String tableFilterPattern, List<String> tableTypes, boolean includeSchema, CallOption... options)	Request a list of tables.
SchemaResult	getTablesSchema(boolean includeSchema, CallOption... options)	Get the schema of getTables(String, String, String, List, boolean, CallOption...) from the server.
FlightInfo	getTableTypes(CallOption... options)	Request a list of table types.
SchemaResult	getTableTypesSchema(CallOption... options)	Get the schema of getTableTypes(CallOption...) from the server.
FlightInfo	getXdbcTypeInfo(int dataType, CallOption... options)	Request the information about the data types supported related to a filter data type.
FlightInfo	getXdbcTypeInfo(CallOption... options)	Request the information about all the data types supported.
SchemaResult	getXdbcTypeInfoSchema(CallOption... options)	Get the schema of getXdbcTypeInfo(CallOption...) from the server.
FlightSqlClient.PreparedStatement	prepare(String query, CallOption... options)	Create a prepared statement for a SQL query on the server.
FlightSqlClient.PreparedStatement	prepare(String query, FlightSqlClient.Transaction transaction, CallOption... options)	Create a prepared statement for a SQL query on the server.
FlightSqlClient.PreparedStatement	prepare(FlightSqlClient.SubstraitPlan plan, CallOption... options)	Create a prepared statement for a Substrait plan on the server.
FlightSqlClient.PreparedStatement	prepare(FlightSqlClient.SubstraitPlan plan, FlightSqlClient.Transaction transaction, CallOption... options)	Create a prepared statement for a Substrait plan on the server.
void	release(FlightSqlClient.Savepoint savepoint, CallOption... options)	Release a savepoint.
FlightEndpoint	renewFlightEndpoint(RenewFlightEndpointRequest request, CallOption... options)	Request the server to extend the lifetime of a query result set.
void	rollback(FlightSqlClient.Savepoint savepoint, CallOption... options)	Rollback to a savepoint.
void	rollback(FlightSqlClient.Transaction transaction, CallOption... options)	Rollback a transaction.
SetSessionOptionsResult	setSessionOptions(SetSessionOptionsRequest request, CallOption... options)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

FlightSqlClient

public FlightSqlClient(FlightClient client)

Method Details

execute

public FlightInfo execute(String query,
 CallOption... options)

Execute a query on the server.

Parameters:

query - The query to execute.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

execute

public FlightInfo execute(String query,
 FlightSqlClient.Transaction transaction,
 CallOption... options)

Execute a query on the server.

Parameters:

query - The query to execute.

transaction - The transaction that this query is part of.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

executeSubstrait

public FlightInfo executeSubstrait(FlightSqlClient.SubstraitPlan plan,
 CallOption... options)

Execute a Substrait plan on the server.

Parameters:

plan - The Substrait plan to execute.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

executeSubstrait

public FlightInfo executeSubstrait(FlightSqlClient.SubstraitPlan plan,
 FlightSqlClient.Transaction transaction,
 CallOption... options)

Execute a Substrait plan on the server.

Parameters:

plan - The Substrait plan to execute.

transaction - The transaction that this query is part of.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getExecuteSchema

public SchemaResult getExecuteSchema(String query,
 FlightSqlClient.Transaction transaction,
 CallOption... options)

Get the schema of the result set of a query.

getExecuteSchema

public SchemaResult getExecuteSchema(String query,
 CallOption... options)

Get the schema of the result set of a query.

getExecuteSubstraitSchema

public SchemaResult getExecuteSubstraitSchema(FlightSqlClient.SubstraitPlan plan,
 FlightSqlClient.Transaction transaction,
 CallOption... options)

Get the schema of the result set of a Substrait plan.

getExecuteSubstraitSchema

public SchemaResult getExecuteSubstraitSchema(FlightSqlClient.SubstraitPlan substraitPlan,
 CallOption... options)

Get the schema of the result set of a Substrait plan.

executeUpdate

public long executeUpdate(String query,
 CallOption... options)

Execute an update query on the server.

Parameters:

query - The query to execute.

options - RPC-layer hints for this call.

Returns:

the number of rows affected.

executeUpdate

public long executeUpdate(String query,
 FlightSqlClient.Transaction transaction,
 CallOption... options)

Execute an update query on the server.

Parameters:

query - The query to execute.

transaction - The transaction that this query is part of.

options - RPC-layer hints for this call.

Returns:

the number of rows affected.

executeSubstraitUpdate

public long executeSubstraitUpdate(FlightSqlClient.SubstraitPlan plan,
 CallOption... options)

Execute an update query on the server.

Parameters:

plan - The Substrait plan to execute.

options - RPC-layer hints for this call.

Returns:

the number of rows affected.

executeSubstraitUpdate

public long executeSubstraitUpdate(FlightSqlClient.SubstraitPlan plan,
 FlightSqlClient.Transaction transaction,
 CallOption... options)

Execute an update query on the server.

Parameters:

plan - The Substrait plan to execute.

transaction - The transaction that this query is part of.

options - RPC-layer hints for this call.

Returns:

the number of rows affected.

getCatalogs

public FlightInfo getCatalogs(CallOption... options)

Request a list of catalogs.

Parameters:

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getCatalogsSchema

public SchemaResult getCatalogsSchema(CallOption... options)

Get the schema of getCatalogs(CallOption...) from the server.

Should be identical to FlightSqlProducer.Schemas.GET_CATALOGS_SCHEMA.

getSchemas

public FlightInfo getSchemas(String catalog,
 String dbSchemaFilterPattern,
 CallOption... options)

Request a list of schemas.

Parameters:

catalog - The catalog.

dbSchemaFilterPattern - The schema filter pattern.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getSchemasSchema

public SchemaResult getSchemasSchema(CallOption... options)

Get the schema of getSchemas(String, String, CallOption...) from the server.

Should be identical to FlightSqlProducer.Schemas.GET_SCHEMAS_SCHEMA.

getSchema

public SchemaResult getSchema(FlightDescriptor descriptor,
 CallOption... options)

Get schema for a stream.

Parameters:

descriptor - The descriptor for the stream.

options - RPC-layer hints for this call.

getStream

public FlightStream getStream(Ticket ticket,
 CallOption... options)

Retrieve a stream from the server.

Parameters:

ticket - The ticket granting access to the data stream.

options - RPC-layer hints for this call.

getSqlInfo

public FlightInfo getSqlInfo(FlightSql.SqlInfo... info)

Request a set of Flight SQL metadata.

Parameters:

info - The set of metadata to retrieve. None to retrieve all metadata.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getSqlInfo

public FlightInfo getSqlInfo(FlightSql.SqlInfo[] info,
 CallOption... options)

Request a set of Flight SQL metadata.

Parameters:

info - The set of metadata to retrieve. None to retrieve all metadata.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getSqlInfo

public FlightInfo getSqlInfo(int[] info,
 CallOption... options)

Request a set of Flight SQL metadata. Use this method if you would like to retrieve custom metadata, where the custom metadata key values start from 10_000.

Parameters:

info - The set of metadata to retrieve. None to retrieve all metadata.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getSqlInfo

public FlightInfo getSqlInfo(Iterable<Integer> info,
 CallOption... options)

Request a set of Flight SQL metadata. Use this method if you would like to retrieve custom metadata, where the custom metadata key values start from 10_000.

Parameters:

info - The set of metadata to retrieve. None to retrieve all metadata.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getSqlInfoSchema

public SchemaResult getSqlInfoSchema(CallOption... options)

Get the schema of getSqlInfo(SqlInfo...) from the server.

Should be identical to FlightSqlProducer.Schemas.GET_SQL_INFO_SCHEMA.

getXdbcTypeInfo

public FlightInfo getXdbcTypeInfo(int dataType,
 CallOption... options)

Request the information about the data types supported related to a filter data type.

Parameters:

dataType - the data type to be used as filter.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getXdbcTypeInfo

public FlightInfo getXdbcTypeInfo(CallOption... options)

Request the information about all the data types supported.

Parameters:

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getXdbcTypeInfoSchema

public SchemaResult getXdbcTypeInfoSchema(CallOption... options)

Get the schema of getXdbcTypeInfo(CallOption...) from the server.

Should be identical to FlightSqlProducer.Schemas.GET_TYPE_INFO_SCHEMA.

getTables

public FlightInfo getTables(String catalog,
 String dbSchemaFilterPattern,
 String tableFilterPattern,
 List<String> tableTypes,
 boolean includeSchema,
 CallOption... options)

Request a list of tables.

Parameters:

catalog - The catalog.

dbSchemaFilterPattern - The schema filter pattern.

tableFilterPattern - The table filter pattern.

tableTypes - The table types to include.

includeSchema - True to include the schema upon return, false to not include the schema.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getTablesSchema

public SchemaResult getTablesSchema(boolean includeSchema,
 CallOption... options)

Get the schema of getTables(String, String, String, List, boolean, CallOption...) from the server.

Should be identical to FlightSqlProducer.Schemas.GET_TABLES_SCHEMA or FlightSqlProducer.Schemas.GET_TABLES_SCHEMA_NO_SCHEMA.

getPrimaryKeys

public FlightInfo getPrimaryKeys(TableRef tableRef,
 CallOption... options)

Request the primary keys for a table.

Parameters:

tableRef - An object which hold info about catalog, dbSchema and table.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getPrimaryKeysSchema

public SchemaResult getPrimaryKeysSchema(CallOption... options)

Get the schema of getPrimaryKeys(TableRef, CallOption...) from the server.

Should be identical to FlightSqlProducer.Schemas.GET_PRIMARY_KEYS_SCHEMA.

getExportedKeys

public FlightInfo getExportedKeys(TableRef tableRef,
 CallOption... options)

Retrieves a description about the foreign key columns that reference the primary key columns of the given table.

Parameters:

tableRef - An object which hold info about catalog, dbSchema and table.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getExportedKeysSchema

public SchemaResult getExportedKeysSchema(CallOption... options)

Get the schema of getExportedKeys(TableRef, CallOption...) from the server.

Should be identical to FlightSqlProducer.Schemas.GET_EXPORTED_KEYS_SCHEMA.

getImportedKeys

public FlightInfo getImportedKeys(TableRef tableRef,
 CallOption... options)

Retrieves the foreign key columns for the given table.

Parameters:

tableRef - An object which hold info about catalog, dbSchema and table.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getImportedKeysSchema

public SchemaResult getImportedKeysSchema(CallOption... options)

Get the schema of getImportedKeys(TableRef, CallOption...) from the server.

Should be identical to FlightSqlProducer.Schemas.GET_IMPORTED_KEYS_SCHEMA.

getCrossReference

public FlightInfo getCrossReference(TableRef pkTableRef,
 TableRef fkTableRef,
 CallOption... options)

Retrieves a description of the foreign key columns that reference the given table's primary key columns (the foreign keys exported by a table).

Parameters:

pkTableRef - An object which hold info about catalog, dbSchema and table from a primary table.

fkTableRef - An object which hold info about catalog, dbSchema and table from a foreign table.

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getCrossReferenceSchema

public SchemaResult getCrossReferenceSchema(CallOption... options)

Get the schema of getCrossReference(TableRef, TableRef, CallOption...) from the server.

Should be identical to FlightSqlProducer.Schemas.GET_CROSS_REFERENCE_SCHEMA.

getTableTypes

public FlightInfo getTableTypes(CallOption... options)

Request a list of table types.

Parameters:

options - RPC-layer hints for this call.

Returns:

a FlightInfo object representing the stream(s) to fetch.

getTableTypesSchema

public SchemaResult getTableTypesSchema(CallOption... options)

Get the schema of getTableTypes(CallOption...) from the server.

Should be identical to FlightSqlProducer.Schemas.GET_TABLE_TYPES_SCHEMA.

prepare

public FlightSqlClient.PreparedStatement prepare(String query,
 CallOption... options)

Create a prepared statement for a SQL query on the server.

Parameters:

query - The query to prepare.

options - RPC-layer hints for this call.

Returns:

The representation of the prepared statement which exists on the server.

prepare

public FlightSqlClient.PreparedStatement prepare(String query,
 FlightSqlClient.Transaction transaction,
 CallOption... options)

Create a prepared statement for a SQL query on the server.

Parameters:

query - The query to prepare.

transaction - The transaction that this query is part of.

options - RPC-layer hints for this call.

Returns:

The representation of the prepared statement which exists on the server.

prepare

public FlightSqlClient.PreparedStatement prepare(FlightSqlClient.SubstraitPlan plan,
 CallOption... options)

Create a prepared statement for a Substrait plan on the server.

Parameters:

plan - The query to prepare.

options - RPC-layer hints for this call.

Returns:

The representation of the prepared statement which exists on the server.

prepare

public FlightSqlClient.PreparedStatement prepare(FlightSqlClient.SubstraitPlan plan,
 FlightSqlClient.Transaction transaction,
 CallOption... options)

Create a prepared statement for a Substrait plan on the server.

Parameters:

plan - The query to prepare.

transaction - The transaction that this query is part of.

options - RPC-layer hints for this call.

Returns:

The representation of the prepared statement which exists on the server.

beginTransaction

public FlightSqlClient.Transaction beginTransaction(CallOption... options)

Begin a transaction.

beginSavepoint

public FlightSqlClient.Savepoint beginSavepoint(FlightSqlClient.Transaction transaction,
 String name,
 CallOption... options)

Create a savepoint within a transaction.

commit

public void commit(FlightSqlClient.Transaction transaction,
 CallOption... options)

Commit a transaction.

release

public void release(FlightSqlClient.Savepoint savepoint,
 CallOption... options)

Release a savepoint.

rollback

public void rollback(FlightSqlClient.Transaction transaction,
 CallOption... options)

Rollback a transaction.

rollback

public void rollback(FlightSqlClient.Savepoint savepoint,
 CallOption... options)

Rollback to a savepoint.

cancelFlightInfo

public CancelFlightInfoResult cancelFlightInfo(CancelFlightInfoRequest request,
 CallOption... options)

Cancel execution of a distributed query.

Parameters:

request - The query to cancel.

options - Call options.

Returns:

The server response.

cancelQuery

@Deprecated
public CancelResult cancelQuery(FlightInfo info,
 CallOption... options)

Deprecated.

Prefer cancelFlightInfo(org.apache.arrow.flight.CancelFlightInfoRequest, org.apache.arrow.flight.CallOption...).

Explicitly cancel a running query.

This lets a single client explicitly cancel work, no matter how many clients are involved/whether the query is distributed or not, given server support. The transaction/statement is not rolled back; it is the application's job to commit or rollback as appropriate. This only indicates the client no longer wishes to read the remainder of the query results or continue submitting data.

renewFlightEndpoint

public FlightEndpoint renewFlightEndpoint(RenewFlightEndpointRequest request,
 CallOption... options)

Request the server to extend the lifetime of a query result set.

Parameters:

request - The result set partition.

options - Call options.

Returns:

The new endpoint with an updated expiration time.

setSessionOptions

public SetSessionOptionsResult setSessionOptions(SetSessionOptionsRequest request,
 CallOption... options)

getSessionOptions

public GetSessionOptionsResult getSessionOptions(GetSessionOptionsRequest request,
 CallOption... options)

closeSession

public CloseSessionResult closeSession(CloseSessionRequest request,
 CallOption... options)

close

public void close()
           throws Exception

Specified by:

close in interface AutoCloseable

Throws:

Exception