View Source Duckdbex (Duckdbex v0.3.1)

DuckDB API module

Summary

Functions

Creates the Appender to load bulk data into a DuckDB database.

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.

Commit the changes made by the appender.

Returns columns names from the query result.

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.

Convert a duckdb hugeint record to erlang/elixir integer.

Convert an erlang/elixir integer to a DuckDB hugeint.

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.

Returns the commit hash of the linked DuckDB library

Returns the version number of the database storage format

Types

@type appender() :: reference()
@type connection() :: reference()
@type db() :: reference()
@type query_result() :: reference()
@type reason() :: :atom | binary()
@type statement() :: reference()

Functions

Link to this function

appender(connection, table_name)

View Source
@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")

Link to this function

appender_add_row(appender, row)

View Source
@spec appender_add_row(appender(), list()) :: :ok | {:error, reason()}

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])

Link to this function

appender_add_rows(appender, rows)

View Source
@spec appender_add_rows(appender(), [list()]) :: :ok | {:error, reason()}

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"]])

Link to this function

appender_close(appender)

View Source
@spec appender_close(appender()) :: :ok | {:error, reason()}

Flush the changes made by the appender and close it.

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)

Link to this function

appender_flush(appender)

View Source
@spec appender_flush(appender()) :: :ok | {:error, reason()}

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 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 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)

Link to this function

execute_statement(statement)

View Source
@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)

Link to this function

execute_statement(statement, args)

View Source
@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)

Link to this function

extension_is_loaded(db, extension_name)

View Source
@spec extension_is_loaded(db(), binary()) :: boolean()

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)

Link to this function

fetch_chunk(query_result)

View Source
@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)

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)

Link to this function

integer_to_hugeint(integer)

View Source

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, hugeint}]) iex> [[{5325, 4808176044395724800}]] = Duckdbex.fetch_all(res)

@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"

Link to this function

library_version(storage_format_version)

View Source
@spec library_version(integer()) :: binary()

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"

@spec number_of_threads(db()) :: integer()

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

@spec open() :: {:ok, db()} | {:error, reason()}

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"

Link to this function

prepare_statement(connection, sql_string)

View Source
@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;")

Link to this function

query(connection, sql_string)

View Source
@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;")

Link to this function

query(connection, sql_string, args)

View Source
@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 source_id() :: binary()

Returns the commit hash of the linked DuckDB library

Examples

iex> Duckdbex.source_id() iex> "b00b93f0b1"

Link to this function

storage_format_version()

View Source
@spec storage_format_version() :: integer()

Returns the version number of the database storage format

Examples

iex> Duckdbex.storage_format_version() iex> 43