View Source Duckdbex (Duckdbex v0.3.11)
DuckDB API module
Summary
Functions
Creates the Appender to load bulk data into a DuckDB database.
Creates the Appender to load bulk data into a DuckDB database with schema name.
Append row into a DuckDB database table.
Append multiple rows into a DuckDB database table at once.
Flush the changes made by the appender and close it. Also it will release appender resource (see Duckdbex.release(resource))
Commit the changes made by the appender.
Begin a transaction
Returns columns names from the query result.
Commit the transaction
Creates connection object to work with database.
Execute the prepared statement
Execute the prepared statement with the given list of parameters
Returns whether extension is loaded
Fetches all data from the query result.
Fetches a data chunk from the query result.
Checks if there is an active transaction for connection
Convert a duckdb hugeint record to erlang/elixir integer.
Convert an erlang/elixir integer to a DuckDB hugeint.
Check if transaction autocommit is set for connection
Returns the version of the linked DuckDB, with a version postfix for dev versions
Returns the version of the DuckDB library, for storage format version
Returns the count of DuckDB threads
Opens database in the memory.
If the path to the file is specified, then opens the database in the file.
Opens database in the specified file.
Returns the Platform of the linked DuckDB library
Prepare the specified query, returning a reference to the prepared statement object
Issues a query to the database and returns a result reference.
Issues a query to the database with parameters and returns a result reference.
Release resource (db, connection, stmt, query_result)
Rollback the transaction
Set transaction autocommit for connection
Returns the commit hash of the linked DuckDB library
Returns the version number of the database storage format
Types
Functions
@spec appender(connection(), binary()) :: {:ok, appender()} | {:error, reason()}
Creates the Appender to load bulk data into a DuckDB database.
This is the recommended way to load bulk data.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, _res} = Duckdbex.query(conn, "CREATE TABLE table_1 (data INTEGER);") iex> {:ok, _appender} = Duckdbex.appender(conn, "table_1")
@spec appender(connection(), binary(), binary()) :: {:ok, appender()} | {:error, reason()}
Creates the Appender to load bulk data into a DuckDB database with schema name.
This is the recommended way to load bulk data.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, _res} = Duckdbex.query(conn, "CREATE SCHEMA schema_1") iex> {:ok, _res} = Duckdbex.query(conn, "CREATE TABLE schema_1.table_1 (data INTEGER);") iex> {:ok, _appender} = Duckdbex.appender(conn, "schema_1", "table_1")
Append row into a DuckDB database table.
Any values added to the appender are cached prior to being inserted into the database system for performance reasons. That means that, while appending, the rows might not be immediately visible in the system. The cache is automatically flushed when the appender goes out of scope or when Duckdbex.appender_close(appender) is called. The cache can also be manually flushed using the Duckdbex.appender_flush(appender) method. After either flush or close is called, all the data has been written to the database system.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, _res} = Duckdbex.query(conn, "CREATE TABLE table_1 (data INTEGER);") iex> {:ok, appender} = Duckdbex.appender(conn, "table_1") iex> :ok = Duckdbex.appender_add_row(appender, [1])
Append multiple rows into a DuckDB database table at once.
Any values added to the appender are cached prior to being inserted into the database system for performance reasons. That means that, while appending, the rows might not be immediately visible in the system. The cache is automatically flushed when the appender goes out of scope or when Duckdbex.appender_close/1
is called. The cache can also be manually flushed using the Duckdbex.appender_flush/1
method. After either flush or close is called, all the data has been written to the database system.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, _res} = Duckdbex.query(conn, "CREATE TABLE table_1 (the_n1 INTEGER, the_str1 STRING);") iex> {:ok, appender} = Duckdbex.appender(conn, "table_1") iex> :ok = Duckdbex.appender_add_rows(appender, [[1, "one"], [2, "two"]])
Flush the changes made by the appender and close it. Also it will release appender resource (see Duckdbex.release(resource))
The appender cannot be used after this point
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, _res} = Duckdbex.query(conn, "CREATE TABLE table_1 (the_n1 INTEGER, the_str1 STRING);") iex> {:ok, appender} = Duckdbex.appender(conn, "table_1") iex> :ok = Duckdbex.appender_add_rows(appender, [[1, "one"], [2, "two"]]) iex> {:ok, res} = Duckdbex.query(conn, "SELECT FROM table_1;") iex> [] = Duckdbex.fetch_all(res) iex> :ok = Duckdbex.appender_close(appender) iex> {:ok, res} = Duckdbex.query(conn, "SELECT FROM table_1;") iex> [[1, "one"], [2, "two"]] = Duckdbex.fetch_all(res)
Commit the changes made by the appender.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, _res} = Duckdbex.query(conn, "CREATE TABLE table_1 (the_n1 INTEGER, the_str1 STRING);") iex> {:ok, appender} = Duckdbex.appender(conn, "table_1") iex> :ok = Duckdbex.appender_add_rows(appender, [[1, "one"], [2, "two"]]) iex> {:ok, res} = Duckdbex.query(conn, "SELECT FROM table_1;") iex> [] = Duckdbex.fetch_all(res) iex> :ok = Duckdbex.appender_flush(appender) iex> {:ok, res} = Duckdbex.query(conn, "SELECT FROM table_1;") iex> [[1, "one"], [2, "two"]] = Duckdbex.fetch_all(res)
@spec begin_transaction(connection()) :: :ok | {:error, reason()}
Begin a transaction
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> :ok = Duckdbex.begin_transaction(conn)
@spec columns(query_result()) :: list() | {:error, reason()}
Returns columns names from the query result.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, res} = Duckdbex.query(conn, "SELECT 1 as 'my_name';") iex> ["my_name"] = Duckdbex.columns(res)
@spec commit(connection()) :: :ok | {:error, reason()}
Commit the transaction
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> :ok = Duckdbex.begin_transaction(conn) iex> :ok = Duckdbex.commit(conn)
@spec connection(db()) :: {:ok, connection()} | {:error, reason()}
Creates connection object to work with database.
To work with database the connection object is requiered. Connection object hold a shared reference to database, so it is possible to forget the database reference and hold the connection reference only.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, _conn} = Duckdbex.connection(db)
@spec execute_statement(statement()) :: {:ok, query_result()} | {:error, reason()}
Execute the prepared statement
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, stmt} = Duckdbex.prepare_statement(conn, "SELECT 1;") iex> {:ok, res} = Duckdbex.execute_statement(stmt) iex> [[1]] = Duckdbex.fetch_all(res)
@spec execute_statement(statement(), list()) :: {:ok, query_result()} | {:error, reason()}
Execute the prepared statement with the given list of parameters
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, stmt} = Duckdbex.prepare_statement(conn, "SELECT 1 WHERE $1 = 1;") iex> {:ok, res} = Duckdbex.execute_statement(stmt, [1]) iex> [[1]] = Duckdbex.fetch_all(res)
Returns whether extension is loaded
Examples
iex> {:ok, db} = Duckdbex.open() iex> Duckdbex.extension_is_loaded(db, "parquet") iex> false
@spec fetch_all(query_result()) :: list() | {:error, reason()}
Fetches all data from the query result.
Returns empty list if there are no result to fetch.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, res} = Duckdbex.query(conn, "SELECT 1;") iex> [[1]] = Duckdbex.fetch_all(res)
@spec fetch_chunk(query_result()) :: list() | {:error, reason()}
Fetches a data chunk from the query result.
Returns empty list if there are no more results to fetch.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, res} = Duckdbex.query(conn, "SELECT 1;") iex> [[1]] = Duckdbex.fetch_chunk(res)
@spec has_active_transaction(connection()) :: {:ok, boolean()} | {:error, reason()}
Checks if there is an active transaction for connection
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, false} = Duckdbex.has_active_transaction(conn)
Convert a duckdb hugeint record to erlang/elixir integer.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, _res} = Duckdbex.query(conn, "CREATE TABLE hugeints(value HUGEINT);") iex> {:ok, _res} = Duckdbex.query(conn, "INSERT INTO hugeints VALUES (98233720368547758080000::hugeint);") iex> {:ok, res} = Duckdbex.query(conn, "SELECT * FROM hugeints;") iex> [[hugeint = {5325, 4808176044395724800}]] = Duckdbex.fetch_all(res) iex> 98233720368547758080000 = Duckdbex.hugeint_to_integer(hugeint)
Convert an erlang/elixir integer to a DuckDB hugeint.
For more information on DuckDB numeric types, see DuckDB Numeric Data Types For more information on DuckDB numeric types.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, _res} = Duckdbex.query(conn, "CREATE TABLE hugeints(value HUGEINT);") iex> {:ok, _res} = Duckdbex.query(conn, "INSERT INTO hugeints VALUES (98233720368547758080000::hugeint);") iex> hugeint = Duckdbex.integer_to_hugeint(98233720368547758080000) iex> {:ok, res} = Duckdbex.query(conn, "SELECT * FROM hugeints WHERE value = $1", [hugeint]) iex> [[{5325, 4808176044395724800}]] = Duckdbex.fetch_all(res)
@spec is_auto_commit(connection()) :: {:ok, boolean()} | {:error, reason()}
Check if transaction autocommit is set for connection
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, true} = Duckdbex.is_auto_commit(conn)
@spec library_version() :: binary()
Returns the version of the linked DuckDB, with a version postfix for dev versions
Usually used for developing C extensions that must return this for a compatibility check.
Examples
iex> Duckdbex.library_version() iex> "v0.7.0"
Returns the version of the DuckDB library, for storage format version
Examples
iex> Duckdbex.library_version(39) iex> "v0.6.0 or v0.6.1"
Returns the count of DuckDB threads
This is DuckDB own native threads (not a dirty scheduler Erlang threads)
Examples
iex> {:ok, db} = Duckdbex.open() iex> Duckdbex.number_of_threads(db) iex> 8
Opens database in the memory.
Examples
iex> {:ok, _db} = Duckdbex.open()
@spec open(binary() | Duckdbex.Config.t()) :: {:ok, db()} | {:error, reason()}
If the path to the file is specified, then opens the database in the file.
If specified file does not exist, a new database file with the given name will be created automatically. If database config is specified, then opens the database in the memory with the custom database config.
Examples
iex> {:ok, _db} = Duckdbex.open("my_database.duckdb")
iex> {:ok, _db} = Duckdbex.open(%Duckdbex.Config{access_mode: :automatic})
@spec open(binary(), Duckdbex.Config.t() | nil) :: {:ok, db()} | {:error, reason()}
Opens database in the specified file.
If specified file does not exist, a new database file with the given name will be created automatically.
Examples
iex> {:ok, _db} = Duckdbex.open("my_database.duckdb", %Duckdbex.Config{})
@spec platform() :: binary()
Returns the Platform of the linked DuckDB library
Examples
iex> Duckdbex.platform() iex> "osx_amd64"
@spec prepare_statement(connection(), binary()) :: {:ok, statement()} | {:error, reason()}
Prepare the specified query, returning a reference to the prepared statement object
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, _stmt} = Duckdbex.prepare_statement(conn, "SELECT 1 WHERE $1 = 1;")
@spec query(connection(), binary()) :: {:ok, query_result()} | {:error, reason()}
Issues a query to the database and returns a result reference.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, _res} = Duckdbex.query(conn, "SELECT 1;")
@spec query(connection(), binary(), list()) :: {:ok, query_result()} | {:error, reason()}
Issues a query to the database with parameters and returns a result reference.
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, _res} = Duckdbex.query(conn, "SELECT 1 WHERE $1 = 1;", [1])
@spec release(db() | connection() | statement() | query_result() | appender()) :: :ok
Release resource (db, connection, stmt, query_result)
Will cause destruction and automatic closing the releasing resource in the calling process on dirty schedulers. The released resource cannot be used after this point.
If you do not release some resource you have the resource will be automatically released by the Erlang garbage collector (GC) when you lose last ref to the resource, but the GC may run resource releasing in the main schedulers which may affect the performance of your main system perfomance.
Examples
iex> {:ok, db} = Duckdbex.open("my_database.duckdb", %Duckdbex.Config{}) iex> {:ok, conn} = Duckdbex.connection(db) iex> {:ok, res} = Duckdbex.query(conn, "SELECT 1 WHERE $1 = 1;", [1]) iex> :ok = Duckdbex.release(res) iex> :ok = Duckdbex.release(conn) iex> :ok = Duckdbex.release(db)
@spec rollback(connection()) :: :ok | {:error, reason()}
Rollback the transaction
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> :ok = Duckdbex.begin_transaction(conn) iex> :ok = Duckdbex.rollback(conn)
@spec set_auto_commit(connection(), boolean()) :: :ok | {:error, reason()}
Set transaction autocommit for connection
Examples
iex> {:ok, db} = Duckdbex.open() iex> {:ok, conn} = Duckdbex.connection(db) iex> :ok = Duckdbex.set_auto_commit(conn, true)
@spec source_id() :: binary()
Returns the commit hash of the linked DuckDB library
Examples
iex> Duckdbex.source_id() iex> "b00b93f0b1"
@spec storage_format_version() :: integer()
Returns the version number of the database storage format
Examples
iex> Duckdbex.storage_format_version() iex> 43