Title: | 'Arrow' Database Connectivity ('ADBC') Driver Manager |
---|---|
Description: | Provides a developer-facing interface to 'Arrow' Database Connectivity ('ADBC') for the purposes of driver development, driver testing, and building high-level database interfaces for users. 'ADBC' <https://arrow.apache.org/adbc/> is an API standard for database access libraries that uses 'Arrow' for result sets and query parameters. |
Authors: | Dewey Dunnington [aut, cre] , Apache Arrow [aut, cph], Apache Software Foundation [cph] |
Maintainer: | Dewey Dunnington <[email protected]> |
License: | Apache License (>= 2) |
Version: | 0.14.0 |
Built: | 2024-11-04 02:47:33 UTC |
Source: | https://github.com/apache/arrow-adbc |
Connection methods
adbc_connection_get_info(connection, info_codes = NULL) adbc_connection_get_objects( connection, depth = 0L, catalog = NULL, db_schema = NULL, table_name = NULL, table_type = NULL, column_name = NULL ) adbc_connection_get_table_schema(connection, catalog, db_schema, table_name) adbc_connection_get_table_types(connection) adbc_connection_read_partition(connection, serialized_partition) adbc_connection_commit(connection) adbc_connection_rollback(connection) adbc_connection_cancel(connection) adbc_connection_get_statistic_names(connection) adbc_connection_get_statistics( connection, catalog, db_schema, table_name, approximate = FALSE ) adbc_connection_quote_identifier(connection, value, ...) adbc_connection_quote_string(connection, value, ...)
adbc_connection_get_info(connection, info_codes = NULL) adbc_connection_get_objects( connection, depth = 0L, catalog = NULL, db_schema = NULL, table_name = NULL, table_type = NULL, column_name = NULL ) adbc_connection_get_table_schema(connection, catalog, db_schema, table_name) adbc_connection_get_table_types(connection) adbc_connection_read_partition(connection, serialized_partition) adbc_connection_commit(connection) adbc_connection_rollback(connection) adbc_connection_cancel(connection) adbc_connection_get_statistic_names(connection) adbc_connection_get_statistics( connection, catalog, db_schema, table_name, approximate = FALSE ) adbc_connection_quote_identifier(connection, value, ...) adbc_connection_quote_string(connection, value, ...)
connection |
|
info_codes |
A list of metadata codes to fetch, or NULL to fetch all. Valid values are documented in the adbc.h header. |
depth |
The level of nesting to display. If 0, display all levels. If 1, display only catalogs (i.e., catalog_schemas will be null). If 2, display only catalogs and schemas (i.e., db_schema_tables will be null). If 3, display only catalogs, schemas, and tables. |
catalog |
Only show tables in the given catalog. If NULL, do not filter by catalog. If an empty string, only show tables without a catalog. May be a search pattern. |
db_schema |
Only show tables in the given database schema. If NULL, do not filter by database schema. If an empty string, only show tables without a database schema. May be a search pattern. |
table_name |
Constrain an object or statistics query for a specific table. If NULL, do not filter by name. May be a search pattern. |
table_type |
Only show tables matching one of the given table types. If NULL, show tables of any type. Valid table types can be fetched from GetTableTypes. Terminate the list with a NULL entry. |
column_name |
Only show columns with the given name. If NULL, do not filter by name. May be a search pattern. |
serialized_partition |
The partition descriptor. |
approximate |
If |
value |
A string or identifier. |
... |
Driver-specific options. For the default method, these are named values that are converted to strings. |
adbc_connection_get_info()
, adbc_connection_get_objects()
,
adbc_connection_get_table_types()
, and adbc_connection_read_partition()
return a nanoarrow_array_stream.
adbc_connection_get_table_schema()
returns a
nanoarrow_schena
adbc_connection_commit()
and adbc_connection_rollback()
return
connection
, invisibly.
db <- adbc_database_init(adbc_driver_void()) con <- adbc_connection_init(db) # (not implemented by the void driver) try(adbc_connection_get_info(con, 0))
db <- adbc_database_init(adbc_driver_void()) con <- adbc_connection_init(db) # (not implemented by the void driver) try(adbc_connection_get_info(con, 0))
Connections
adbc_connection_init(database, ...) adbc_connection_init_default(database, options = NULL, subclass = character()) adbc_connection_release(connection) adbc_connection_set_options(connection, options) adbc_connection_get_option(connection, option) adbc_connection_get_option_bytes(connection, option) adbc_connection_get_option_int(connection, option) adbc_connection_get_option_double(connection, option)
adbc_connection_init(database, ...) adbc_connection_init_default(database, options = NULL, subclass = character()) adbc_connection_release(connection) adbc_connection_set_options(connection, options) adbc_connection_get_option(connection, option) adbc_connection_get_option_bytes(connection, option) adbc_connection_get_option_int(connection, option) adbc_connection_get_option_double(connection, option)
database |
An adbc_database. |
... |
Driver-specific options. For the default method, these are named values that are converted to strings. |
options |
A named |
subclass |
An extended class for an object so that drivers can specify finer-grained control over behaviour at the R level. |
connection |
|
option |
A specific option name |
An object of class 'adbc_connection'
db <- adbc_database_init(adbc_driver_void()) adbc_connection_init(db)
db <- adbc_database_init(adbc_driver_void()) adbc_connection_init(db)
It is occasionally useful to return a connection, statement, or stream from a function that was created from a unique parent. These helpers tie the lifecycle of a unique parent object to its child such that the parent object is released predictably and immediately after the child. These functions will invalidate all references to the previous R object.
adbc_connection_join(connection, database) adbc_statement_join(statement, connection)
adbc_connection_join(connection, database) adbc_statement_join(statement, connection)
connection |
A connection created with |
database |
A database created with |
statement |
A statement created with |
The input, invisibly.
# Use local_adbc to ensure prompt cleanup on error; # use join functions to return a single object that manages # the lifecycle of all three. stmt <- local({ db <- local_adbc(adbc_database_init(adbc_driver_log())) con <- local_adbc(adbc_connection_init(db)) adbc_connection_join(con, db) stmt <- local_adbc(adbc_statement_init(con)) adbc_statement_join(stmt, con) adbc_xptr_move(stmt) }) # Everything is released immediately when the last object is released adbc_statement_release(stmt)
# Use local_adbc to ensure prompt cleanup on error; # use join functions to return a single object that manages # the lifecycle of all three. stmt <- local({ db <- local_adbc(adbc_database_init(adbc_driver_log())) con <- local_adbc(adbc_connection_init(db)) adbc_connection_join(con, db) stmt <- local_adbc(adbc_statement_init(con)) adbc_statement_join(stmt, con) adbc_xptr_move(stmt) }) # Everything is released immediately when the last object is released adbc_statement_release(stmt)
Databases
adbc_database_init(driver, ...) adbc_database_init_default(driver, options = NULL, subclass = character()) adbc_database_release(database) adbc_database_set_options(database, options) adbc_database_get_option(database, option) adbc_database_get_option_bytes(database, option) adbc_database_get_option_int(database, option) adbc_database_get_option_double(database, option)
adbc_database_init(driver, ...) adbc_database_init_default(driver, options = NULL, subclass = character()) adbc_database_release(database) adbc_database_set_options(database, options) adbc_database_get_option(database, option) adbc_database_get_option_bytes(database, option) adbc_database_get_option_int(database, option) adbc_database_get_option_double(database, option)
driver |
An |
... |
Driver-specific options. For the default method, these are named values that are converted to strings. |
options |
A named |
subclass |
An extended class for an object so that drivers can specify finer-grained control over behaviour at the R level. |
database |
An adbc_database. |
option |
A specific option name |
An object of class adbc_database
adbc_database_init(adbc_driver_void())
adbc_database_init(adbc_driver_void())
Useful for debugging or ensuring that certain calls occur during initialization and/or cleanup. The current logging output should not be considered stable and may change in future releases.
adbc_driver_log()
adbc_driver_log()
An object of class 'adbc_driver_log'
drv <- adbc_driver_log() db <- adbc_database_init(drv, key = "value") con <- adbc_connection_init(db, key = "value") stmt <- adbc_statement_init(con, key = "value") try(adbc_statement_execute_query(stmt)) adbc_statement_release(stmt) adbc_connection_release(con) adbc_database_release(db)
drv <- adbc_driver_log() db <- adbc_database_init(drv, key = "value") con <- adbc_connection_init(db, key = "value") stmt <- adbc_statement_init(con, key = "value") try(adbc_statement_execute_query(stmt)) adbc_statement_release(stmt) adbc_connection_release(con) adbc_database_release(db)
A driver whose query results are set in advance.
adbc_driver_monkey()
adbc_driver_monkey()
An object of class 'adbc_driver_monkey'
db <- adbc_database_init(adbc_driver_monkey()) con <- adbc_connection_init(db) stmt <- adbc_statement_init(con, mtcars) stream <- nanoarrow::nanoarrow_allocate_array_stream() adbc_statement_execute_query(stmt, stream) as.data.frame(stream$get_next())
db <- adbc_database_init(adbc_driver_monkey()) con <- adbc_connection_init(db) stmt <- adbc_statement_init(con, mtcars) stream <- nanoarrow::nanoarrow_allocate_array_stream() adbc_statement_execute_query(stmt, stream) as.data.frame(stream$get_next())
Creates the R object representation of an ADBC driver, which consists of a name and an initializer function with an optional subclass to control finer-grained behaviour at the R level.
adbc_driver_void() adbc_driver(x, entrypoint = NULL, ..., subclass = character())
adbc_driver_void() adbc_driver(x, entrypoint = NULL, ..., subclass = character())
x , entrypoint
|
An ADBC driver may be defined either as an init function
or as an identifier with an entrypoint name. A driver init func
must be an external pointer to a DL_FUNC with the type
|
... |
Further key/value parameters to store with the (R-level) driver object. |
subclass |
An optional subclass for finer-grained control of behaviour at the R level. |
An object of class 'adbc_driver'
adbc_driver_void()
adbc_driver_void()
Get extended error information from an array stream
adbc_error_from_array_stream(stream)
adbc_error_from_array_stream(stream)
stream |
NULL
if stream was not created by a driver that supports
extended error information or a list whose first element is the
status code and second element is the adbc_error
object. The
acbc_error
must not be accessed if stream
is explicitly released.
db <- adbc_database_init(adbc_driver_monkey()) con <- adbc_connection_init(db) stmt <- adbc_statement_init(con, mtcars) stream <- nanoarrow::nanoarrow_allocate_array_stream() adbc_statement_execute_query(stmt, stream) adbc_error_from_array_stream(stream)
db <- adbc_database_init(adbc_driver_monkey()) con <- adbc_connection_init(db) stmt <- adbc_statement_init(con, mtcars) stream <- nanoarrow::nanoarrow_allocate_array_stream() adbc_statement_execute_query(stmt, stream) adbc_error_from_array_stream(stream)
Statements
adbc_statement_init(connection, ...) adbc_statement_init_default(connection, options = NULL, subclass = character()) adbc_statement_release(statement) adbc_statement_set_options(statement, options) adbc_statement_get_option(statement, option) adbc_statement_get_option_bytes(statement, option) adbc_statement_get_option_int(statement, option) adbc_statement_get_option_double(statement, option)
adbc_statement_init(connection, ...) adbc_statement_init_default(connection, options = NULL, subclass = character()) adbc_statement_release(statement) adbc_statement_set_options(statement, options) adbc_statement_get_option(statement, option) adbc_statement_get_option_bytes(statement, option) adbc_statement_get_option_int(statement, option) adbc_statement_get_option_double(statement, option)
connection |
|
... |
Driver-specific options. For the default method, these are named values that are converted to strings. |
options |
A named |
subclass |
An extended class for an object so that drivers can specify finer-grained control over behaviour at the R level. |
statement |
|
option |
A specific option name |
An object of class 'adbc_statement'
db <- adbc_database_init(adbc_driver_void()) con <- adbc_connection_init(db) adbc_statement_init(con)
db <- adbc_database_init(adbc_driver_void()) con <- adbc_connection_init(db) adbc_statement_init(con)
Statement methods
adbc_statement_set_sql_query(statement, query) adbc_statement_set_substrait_plan(statement, plan) adbc_statement_prepare(statement) adbc_statement_get_parameter_schema(statement) adbc_statement_bind(statement, values, schema = NULL) adbc_statement_bind_stream(statement, stream, schema = NULL) adbc_statement_execute_query( statement, stream = NULL, stream_join_parent = FALSE ) adbc_statement_execute_schema(statement) adbc_statement_cancel(statement)
adbc_statement_set_sql_query(statement, query) adbc_statement_set_substrait_plan(statement, plan) adbc_statement_prepare(statement) adbc_statement_get_parameter_schema(statement) adbc_statement_bind(statement, values, schema = NULL) adbc_statement_bind_stream(statement, stream, schema = NULL) adbc_statement_execute_query( statement, stream = NULL, stream_join_parent = FALSE ) adbc_statement_execute_schema(statement) adbc_statement_cancel(statement)
statement |
|
query |
An SQL query as a string |
plan |
A raw vector representation of a serialized Substrait plan. |
values |
A nanoarrow_array or object that can be coerced to one. |
schema |
A nanoarrow_schema or object that can be coerced to one. |
stream |
A nanoarrow_array_stream or object that can be coerced to one. |
stream_join_parent |
Use |
adbc_statement_set_sql_query()
, adbc_statement_set_substrait_plan()
,
adbc_statement_prepare()
, adbc_statement_bind()
,
adbc_statement_bind_stream()
, and adbc_statement_execute_query()
return statement
, invisibly.
adbc_statement_get_parameter_schema()
returns a
nanoarrow_schema.
db <- adbc_database_init(adbc_driver_void()) con <- adbc_connection_init(db) stmt <- adbc_statement_init(con) # (not implemented by the void driver) try(adbc_statement_set_sql_query(stmt, "some query"))
db <- adbc_database_init(adbc_driver_void()) con <- adbc_connection_init(db) stmt <- adbc_statement_init(con) # (not implemented by the void driver) try(adbc_statement_set_sql_query(stmt, "some query"))
adbc_xptr_move()
allocates a fresh R object and moves all values pointed
to by x
into it. The original R object is invalidated by zeroing its
content. This is useful when returning from a function where
lifecycle helpers were used to manage the original
object.
adbc_xptr_is_valid()
provides a means by which to test for an invalidated
pointer.
adbc_xptr_move(x, check_child_count = TRUE) adbc_xptr_is_valid(x)
adbc_xptr_move(x, check_child_count = TRUE) adbc_xptr_is_valid(x)
x |
An 'adbc_database', 'adbc_connection', 'adbc_statement', or 'nanoarrow_array_stream' |
check_child_count |
Ensures that |
adbc_xptr_move()
: A freshly-allocated R object identical to x
adbc_xptr_is_valid()
: Returns FALSE if the ADBC object pointed to by x
has been invalidated.
db <- adbc_database_init(adbc_driver_void()) adbc_xptr_is_valid(db) db_new <- adbc_xptr_move(db) adbc_xptr_is_valid(db) adbc_xptr_is_valid(db_new)
db <- adbc_database_init(adbc_driver_void()) adbc_xptr_is_valid(db) db_new <- adbc_xptr_move(db) adbc_xptr_is_valid(db) adbc_xptr_is_valid(db_new)
These are convenience methods useful for testing connections. Note that
S3 dispatch is always on db_or_con
(i.e., drivers may provide their own
implementations).
read_adbc(db_or_con, query, ..., bind = NULL) execute_adbc(db_or_con, query, ..., bind = NULL) write_adbc( tbl, db_or_con, target_table, ..., mode = c("default", "create", "append"), temporary = FALSE )
read_adbc(db_or_con, query, ..., bind = NULL) execute_adbc(db_or_con, query, ..., bind = NULL) write_adbc( tbl, db_or_con, target_table, ..., mode = c("default", "create", "append"), temporary = FALSE )
db_or_con |
An adbc_database or adbc_connection. If a database, a
connection will be opened. For |
query |
An SQL query |
... |
Passed to S3 methods. |
bind |
A data.frame, nanoarrow_array, or nanoarrow_array_stream of bind parameters or NULL to skip the bind/prepare step. |
tbl |
A data.frame, nanoarrow_array, or nanoarrow_array_stream. |
target_table |
A target table name to which |
mode |
One of "create", "append", or "default" (error if the schema is not compatible or append otherwise). |
temporary |
Use TRUE to create a table as a temporary table. |
read_adbc()
: A nanoarrow_array_stream
execute_adbc()
: db_or_con
, invisibly.
write_adbc()
: tbl
, invisibly.
# On a database, connections are opened and closed db <- adbc_database_init(adbc_driver_log()) try(read_adbc(db, "some sql")) try(execute_adbc(db, "some sql")) try(write_adbc(mtcars, db, "some_table")) # Also works on a connection con <- adbc_connection_init(db) try(read_adbc(con, "some sql")) try(execute_adbc(con, "some sql")) try(write_adbc(mtcars, con, "some_table"))
# On a database, connections are opened and closed db <- adbc_database_init(adbc_driver_log()) try(read_adbc(db, "some sql")) try(execute_adbc(db, "some sql")) try(write_adbc(mtcars, db, "some_table")) # Also works on a connection con <- adbc_connection_init(db) try(read_adbc(con, "some sql")) try(execute_adbc(con, "some sql")) try(write_adbc(mtcars, con, "some_table"))
Managing the lifecycle of databases, connections, and statements can be complex and error-prone. The R objects that wrap the underlying ADBC pointers will perform cleanup in the correct order if you rely on garbage collection (i.e., do nothing and let the objects go out of scope); however it is good practice to explicitly clean up these objects. These helpers are designed to make explicit and predictable cleanup easy to accomplish.
with_adbc(x, code) local_adbc(x, .local_envir = parent.frame())
with_adbc(x, code) local_adbc(x, .local_envir = parent.frame())
x |
An ADBC database, ADBC connection, ADBC statement, or nanoarrow_array_stream returned from calls to an ADBC function. |
code |
Code to execute before cleaning up the input. |
.local_envir |
The execution environment whose scope should be tied to the input. |
Note that you can use adbc_connection_join()
and adbc_statement_join()
to tie the lifecycle of the parent object to that of the child object.
These functions mark any previous references to the parent object as
released so you can still use local and with helpers to manage the parent
object before it is joined. Use stream_join_parent = TRUE
in
adbc_statement_execute_query()
to tie the lifecycle of a statement to
the output stream.
with_adbc()
returns the result of code
local_adbc()
returns the input, invisibly.
# Using with_adbc(): with_adbc(db <- adbc_database_init(adbc_driver_void()), { with_adbc(con <- adbc_connection_init(db), { with_adbc(stmt <- adbc_statement_init(con), { # adbc_statement_set_sql_query(stmt, "SELECT * FROM foofy") # adbc_statement_execute_query(stmt) "some result" }) }) }) # Using local_adbc_*() (works best within a function, test, or local()) local({ db <- local_adbc(adbc_database_init(adbc_driver_void())) con <- local_adbc(adbc_connection_init(db)) stmt <- local_adbc(adbc_statement_init(con)) # adbc_statement_set_sql_query(stmt, "SELECT * FROM foofy") # adbc_statement_execute_query(stmt) "some result" })
# Using with_adbc(): with_adbc(db <- adbc_database_init(adbc_driver_void()), { with_adbc(con <- adbc_connection_init(db), { with_adbc(stmt <- adbc_statement_init(con), { # adbc_statement_set_sql_query(stmt, "SELECT * FROM foofy") # adbc_statement_execute_query(stmt) "some result" }) }) }) # Using local_adbc_*() (works best within a function, test, or local()) local({ db <- local_adbc(adbc_database_init(adbc_driver_void())) con <- local_adbc(adbc_connection_init(db)) stmt <- local_adbc(adbc_statement_init(con)) # adbc_statement_set_sql_query(stmt, "SELECT * FROM foofy") # adbc_statement_execute_query(stmt) "some result" })