Module educkdb

Low level erlang API for duckdb databases.

Copyright © 2022 Maas-Maarten Zeeman

Authors: Maas-Maarten Zeeman (mmzeeman@xs4all.nl).

Description

Low level erlang API for duckdb databases.

Data Types

append_response()

append_response() = ok | {error, term()}

appender()

appender() = reference()

bind_response()

bind_response() = ok | {error, term()}

column()

column() = #{data := [data()], type := type_name()}

connection()

connection() = reference()

data()

data() = boolean() | int8() | int16() | int32() | int64() | uint8() | uint16() | uint32() | uint64() | float() | hugeint() | calendar:date() | time() | datetime() | binary() | [data()] | #{binary() => data()} | {map, [data()], [data()]}

data_chunk()

data_chunk() = reference()

database()

database() = reference()

datetime()

datetime() = {calendar:date(), time()}

hugeint()

hugeint() = #hugeint{upper = educkdb:int64(), lower = educkdb:uint64()}

idx()

idx() = 0..18446744073709551615

int16()

int16() = -32767..32767

int32()

int32() = -2147483647..2147483647

int64()

int64() = -9223372036854775807..9223372036854775807

int8()

int8() = -127..127

named_column()

named_column() = #{name := binary(), data := [data()], type := type_name()}

prepared_statement()

prepared_statement() = reference()

result()

result() = reference()

second()

second() = float()

In the range 0.0..60.0

sql()

sql() = iodata()

time()

time() = {calendar:hour(), calendar:minute(), second()}

type_name()

type_name() = boolean | tinyint | smallint | integer | bigint | utinyint | usmallint | uinteger | ubigint | float | double | hugeint | timestamp | date | time | interval | varchar | blob | decimal | timestamp_s | timestamp_ms | timestamp_ns | enum | list | struct | map | uuid | json

Note: decimal, timestamp_s, timestamp_ms, timestamp_ns and interval's are not supported yet.

uint16()

uint16() = 0..65535

uint32()

uint32() = 0..4294967295

uint64()

uint64() = 0..18446744073709551615

uint8()

uint8() = 0..255

Function Index

open/1Open, or create a duckdb database with default options.
open/2Open, or create a duckdb file.
connect/1Connect to the database.
disconnect/1Disconnect from the database.
close/1Close the database.
config_flag_info/0Return a map with config flags, and explanations.
query/2Query the database.
query_cmd/2Query the database.
prepare/2Compile, and prepare a statement for later execution.
execute_prepared/1
execute_prepared_cmd/1
bind_boolean/3Bind a boolean to the prepared statement at the specified index.
bind_int8/3Bind an int8 to the prepared statement at the specified index.
bind_int16/3Bind an int16 to the prepared statement at the specified index.
bind_int32/3Bind an int32 to the prepared statement at the specified index.
bind_int64/3Bind an int64 to the prepared statement at the specified index.
bind_uint8/3Bind an uint8 to the prepared statement at the specified index.
bind_uint16/3Bind an uint8 to the prepared statement at the specified index.
bind_uint32/3Bind an uint32 to the prepared statement at the specified index.
bind_uint64/3Bind an uint64 to the prepared statement at the specified index.
bind_float/3Bind an float to the prepared statement at the specified index.
bind_double/3Bind an uint64 to the prepared statement at the specified index.
bind_date/3Bind a date to the prepared statement at the specified index.
bind_time/3Bind a time to the prepared statement at the specified index.
bind_timestamp/3Bind a timestamp to the prepared statement at the specified index.
bind_varchar/3Bind a iolist as varchar to the prepared statement at the specified index.
bind_null/2Bind a null value to the prepared statement at the specified index.
get_chunks/1Get all data chunks from a query result.
get_chunk/2Get a data chunk from a query result.
chunk_count/1Get the number of data chunks in a query result.
column_names/1Get the column names from the query result.
extract_chunk/1Extract the data from a data chunk.
get_chunk_column_count/1Return the number of columns in the data chunk.
get_chunk_size/1Return the number of tuples in th data chunk.
appender_create/3Create an appender.
append_boolean/2Append a boolean value to the current location in the row.
append_int8/2Append a tinyint to the current location in the row.
append_int16/2Append a smallint to the current location in the row.
append_int32/2Append an integer (32 bit) to the current location in the row.
append_int64/2Append a bigint to the current location in the row.
append_uint8/2Append a utinyint to the current location in the row.
append_uint16/2Append a usmallint to the current location in the row.
append_uint32/2Append an unsigned integer (32 bit) to the current location in the row.
append_uint64/2Append a ubigint to the current location in the row.
append_float/2Append a float to the current location in the row.
append_double/2Append a doulbe to the current location in the row.
append_time/2
append_date/2
append_timestamp/2
append_varchar/2
append_null/1
appender_flush/1
appender_end_row/1
extract_result/1Extract a query result of the first data chunk.
squery/2Do a simple sql query without parameters, and retrieve the result from the first data chunk.
execute/1Execute a prepared statement, and retrieve the first result from the first data chunk.
hugeint_to_integer/1Convert a duckdb hugeint record to erlang integer.
integer_to_hugeint/1Convert an erlang integer to a DuckDB hugeint.
uuid_binary_to_uuid_string/1Convert a binary represented UUID to a printable hex representation.
uuid_string_to_uuid_binary/1Convert a printable UUID to a binary representation.

Function Details

open/1

open(Filename) -> Result

Open, or create a duckdb database with default options.

open/2

open(Filename, Options) -> Result

Open, or create a duckdb file

connect/1

connect(Database) -> Result

Connect to the database. In the background a thread is started which is used by long running commands. Note: It is adviced to use the connection in a single process.

disconnect/1

disconnect(Connection) -> Result

Disconnect from the database. Stops the thread. The calling pid will receive: {disconnect, Ref, ok | {error, _}}.

close/1

close(Database) -> Result

Close the database. All open connections will become unusable.

config_flag_info/0

config_flag_info() -> map()

Return a map with config flags, and explanations. The options can vary depending on the underlying DuckDB version used. For more information about DuckDB configuration options, see: DuckDB Configuration.

query/2

query(Connection, Sql) -> Result

Query the database. The answer the answer is returned immediately. Special care has been taken to prevent blocking the scheduler. A reference to a result data structure will be returned.

query_cmd/2

query_cmd(Conn::connection(), Sql::sql()) -> {ok, reference()} | {error, term()}

Query the database. The answer is send back as a result to the calling process.

prepare/2

prepare(Conn::connection(), Sql::sql()) -> {ok, prepared_statement()} | {error, term()}

Compile, and prepare a statement for later execution.

execute_prepared/1

execute_prepared(PreparedStatement) -> Result

execute_prepared_cmd/1

execute_prepared_cmd(PreparedStatement) -> Result

bind_boolean/3

bind_boolean(PreparedStatement, Index, Boolean) -> BindResponse

Bind a boolean to the prepared statement at the specified index.

bind_int8/3

bind_int8(PreparedStatement, Index, Int8) -> BindResponse

Bind an int8 to the prepared statement at the specified index.

bind_int16/3

bind_int16(PreparedStatement, Index, Int16) -> BindResponse

Bind an int16 to the prepared statement at the specified index.

bind_int32/3

bind_int32(PreparedStatement, Index, Int32) -> BindResponse

Bind an int32 to the prepared statement at the specified index.

bind_int64/3

bind_int64(PreparedStatement, Index, Int64) -> BindResponse

Bind an int64 to the prepared statement at the specified index.

bind_uint8/3

bind_uint8(PreparedStatement, Index, UInt8) -> BindResponse

Bind an uint8 to the prepared statement at the specified index.

bind_uint16/3

bind_uint16(PreparedStatement, Index, UInt16) -> BindResponse

Bind an uint8 to the prepared statement at the specified index.

bind_uint32/3

bind_uint32(PreparedStatement, Index, UInt32) -> BindResponse

Bind an uint32 to the prepared statement at the specified index.

bind_uint64/3

bind_uint64(PreparedStatement, Index, UInt64) -> BindResponse

Bind an uint64 to the prepared statement at the specified index.

bind_float/3

bind_float(PreparedStatement, Index, Float) -> BindResponse

Bind an float to the prepared statement at the specified index. Note: Erlang's float() datatype is actually a DuckDB double. When binding an Erlang float variable you will lose precision.

bind_double/3

bind_double(PreparedStatement, Index, Double) -> BindResponse

Bind an uint64 to the prepared statement at the specified index. Note: Erlang's float datatype is a DuckDB double. Using this function allows you to keep the precision.

bind_date/3

bind_date(PreparedStatement, Index, Date) -> BindResponse

Bind a date to the prepared statement at the specified index. The date can be either given as a calendar:date() tuple, or an integer with the number of days since the first of January in the year 0.

bind_time/3

bind_time(PreparedStatement, Index, Time) -> BindResponse

Bind a time to the prepared statement at the specified index. The time can be either given as an {hour, minute, second} tuple (similar to calendar:time()), or as an integer with the number of microseconds since midnight.

bind_timestamp/3

bind_timestamp(PreparedStatement, Index, TimeStamp) -> BindResponse

Bind a timestamp to the prepared statement at the specified index. The timestamp can be either a datetime tuple, or an integer with the microseconds since 1-Jan in the year 0.

bind_varchar/3

bind_varchar(PreparedStatement, Index, IOData) -> BindResponse

Bind a iolist as varchar to the prepared statement at the specified index. Note: This function is meant to bind null terminated strings in the database. Not arbitrary binary data.

bind_null/2

bind_null(PreparedStatement, Index) -> BindResponse

Bind a null value to the prepared statement at the specified index.

get_chunks/1

get_chunks(QueryResult) -> DataChunks

Get all data chunks from a query result.

get_chunk/2

get_chunk(QueryResult, Idx) -> DataChunk

Get a data chunk from a query result.

chunk_count/1

chunk_count(QueryResult) -> Count

Get the number of data chunks in a query result.

column_names/1

column_names(QueryResult) -> Names

Get the column names from the query result.

extract_chunk/1

extract_chunk(DataChunk) -> Columns

Extract the data from a data chunk. Chunks contain multiple columns and rows. All data in the chunks is extracted.

get_chunk_column_count/1

get_chunk_column_count(DataChunk) -> ColumnCount

Return the number of columns in the data chunk.

get_chunk_size/1

get_chunk_size(DataChunk) -> TupleCount

Return the number of tuples in th data chunk.

appender_create/3

appender_create(Connection, Schema, Table) -> Result

Create an appender. Appenders allow for high speed bulk insertions into the database. See DuckDB Appender for more information.

append_boolean/2

append_boolean(Appender, Boolean) -> AppendResponse

Append a boolean value to the current location in the row.

append_int8/2

append_int8(Appender, TinyInt) -> AppendResponse

Append a tinyint to the current location in the row.

append_int16/2

append_int16(Appender, SmallInt) -> AppendResponse

Append a smallint to the current location in the row.

append_int32/2

append_int32(Appender, Integer) -> AppendResponse

Append an integer (32 bit) to the current location in the row.

append_int64/2

append_int64(Appender, BigInt) -> AppendResponse

Append a bigint to the current location in the row.

append_uint8/2

append_uint8(Appender, UTinyInt) -> AppendResponse

Append a utinyint to the current location in the row.

append_uint16/2

append_uint16(Appender, USmallInt) -> AppendResponse

Append a usmallint to the current location in the row.

append_uint32/2

append_uint32(Appender, UInteger) -> AppendResponse

Append an unsigned integer (32 bit) to the current location in the row.

append_uint64/2

append_uint64(Appender, UBigInt) -> AppendResponse

Append a ubigint to the current location in the row.

append_float/2

append_float(Appender, Float) -> AppendResponse

Append a float to the current location in the row. Note: duckdb floats are different than erlang floats. When you add an erlang float to a duckdb float column, you will loose precision.

append_double/2

append_double(Appender, Double) -> AppendResponse

Append a doulbe to the current location in the row. Note: duckdb double's are the same as erlang floats.

append_time/2

append_time(Appender, Micros) -> any()

append_date/2

append_date(Appender, Date) -> any()

append_timestamp/2

append_timestamp(Appender, Micros) -> any()

append_varchar/2

append_varchar(Appender::appender(), IOData::iodata()) -> append_response()

append_null/1

append_null(Appender::appender()) -> append_response()

appender_flush/1

appender_flush(Appender::appender()) -> append_response()

appender_end_row/1

appender_end_row(Appender::appender()) -> append_response()

extract_result/1

extract_result(QueryResult) -> Chunks

Extract a query result of the first data chunk.

squery/2

squery(Connection, Sql) -> Result

Do a simple sql query without parameters, and retrieve the result from the first data chunk.

execute/1

execute(PreparedStatement) -> Result

Execute a prepared statement, and retrieve the first result from the first data chunk.

hugeint_to_integer/1

hugeint_to_integer(Hugeint) -> Integer

Convert a duckdb hugeint record to erlang integer.

integer_to_hugeint/1

integer_to_hugeint(Integer) -> Hugeint

Convert an erlang integer to a DuckDB hugeint.

For more information on DuckDB numeric types: See DuckDB Numeric Data Types.

uuid_binary_to_uuid_string/1

uuid_binary_to_uuid_string(Bin) -> any()

Convert a binary represented UUID to a printable hex representation.

uuid_string_to_uuid_binary/1

uuid_string_to_uuid_binary(U) -> any()

Convert a printable UUID to a binary representation.


Generated by EDoc