%% @author Maas-Maarten Zeeman <mmzeeman@xs4all.nl>
%% @copyright 2022-2024 Maas-Maarten Zeeman
%%
%% @doc Low level erlang API for duckdb databases.
%% @end
%% Copyright 2022-2024 Maas-Maarten Zeeman <mmzeeman@xs4all.nl>
%%
%% Licensed under the Apache License, Version 2.0 (the "License");
%% you may not use this file except in compliance with the License.
%% You may obtain a copy of the License at
%%
%% http://www.apache.org/licenses/LICENSE-2.0
%%
%% Unless required by applicable law or agreed to in writing, software
%% distributed under the License is distributed on an "AS IS" BASIS,
%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
%% See the License for the specific language governing permissions and
%% limitations under the License.
-module(educkdb).
-author("Maas-Maarten Zeeman <mmzeeman@xs4all.nl>").
%% low-level exports
-export([
open/1, open/2,
close/1,
config_flag_info/0,
connect/1,
disconnect/1,
query/2,
prepare/2,
statement_type/1,
execute_prepared/1,
parameter_name/2,
parameter_type/2,
parameter_count/1,
parameter_index/2,
clear_bindings/1,
bind_boolean/3,
bind_int8/3,
bind_int16/3,
bind_int32/3,
bind_int64/3,
bind_uint8/3,
bind_uint16/3,
bind_uint32/3,
bind_uint64/3,
bind_float/3,
bind_double/3,
bind_date/3,
bind_time/3,
bind_timestamp/3,
bind_varchar/3,
bind_null/2,
%% Results
result_extract/1,
fetch_chunk/1,
get_chunks/1,
column_names/1,
%% Chunks
chunk_column_count/1,
chunk_column_types/1,
chunk_columns/1,
chunk_size/1,
appender_create/3,
append_boolean/2,
append_int8/2,
append_int16/2,
append_int32/2,
append_int64/2,
append_uint8/2,
append_uint16/2,
append_uint32/2,
append_uint64/2,
append_float/2,
append_double/2,
append_time/2,
append_date/2,
append_timestamp/2,
append_varchar/2,
append_null/1,
appender_flush/1,
appender_end_row/1
]).
%% High Level Api
-export([
squery/2,
execute/1
]).
%% Utilities
-export([
uuid_binary_to_uuid_string/1,
uuid_string_to_uuid_binary/1,
hugeint_to_integer/1,
integer_to_hugeint/1,
uhugeint_to_integer/1,
integer_to_uhugeint/1
]).
-include("educkdb.hrl").
-type database() :: reference().
-type connection() :: reference().
-type prepared_statement() :: reference().
-type result() :: reference().
-type appender() :: reference().
-type data_chunk() :: reference().
-type sql() :: iodata().
-type idx() :: uint64(). % DuckDB index type
-type int8() :: -16#7F..16#7F. % DuckDB tinyint
-type uint8() :: 0..16#FF. % DuckDB duckdb utinyint
-type int16() :: -16#7FFF..16#7FFF. % DuckDB shortint
-type uint16() :: 0..16#FFFF. % DuckDB ushortint
-type int32() :: -16#7FFFFFFF..16#7FFFFFFF. % DuckDB integer
-type uint32() :: 0..16#FFFFFFFF. % DuckDB uinteger
-type int64() :: -16#7FFFFFFFFFFFFFFF..16#7FFFFFFFFFFFFFFF. % DuckDB bigint
-type uint64() :: 0..16#FFFFFFFFFFFFFFFF. % DuckDB ubigint
-type hugeint() :: #hugeint{}. % struct, making up a 128 bit signed integer.
-type uhugeint() :: #uhugeint{}. % struct, making up a 128 bit unsigned integer.
-type second() :: calendar:time() | float(). %% In the range 0.0..60.0
-type time() :: {calendar:hour(), calendar:minute(), second()}.
-type datetime() :: {calendar:date(), time()}.
-type data() :: boolean()
| int8() | int16() | int32() | int64()
| uint8() | uint16() | uint32() | uint64()
| float() | hugeint()
| calendar:date() | time() | datetime()
| binary()
| list(data())
| #{binary() => data()}
| {map, list(data()), list(data())}.
-type type_name() :: boolean
| tinyint | smallint | integer | bigint
| utinyint | usmallint | uinteger | ubigint
| float | double | hugeint | uhugeint
| timestamp | date | time
| interval
| varchar | blob
| decimal
| timestamp_s | timestamp_ms | timestamp_ns
| enum
| interval
| list | struct | map
| uuid | json. %% Note: decimal, timestamp_s, timestamp_ms, timestamp_ns and interval's are not supported yet.
-type statement_type() :: invalid
| select | insert | update | explain | delete | prepare | create
| execute | alter | transaction | copy | analyze | variable_set
| create_func | drop | export | pragma | vacuum | call | set | load
| relation | extension | logical_plan | attach | detach | multi
| unknown.
-type named_column() :: #{ name := binary(), data := list(data()), type := type_name() }.
-type bind_response() :: ok | {error, _}.
-type append_response() :: ok | {error, _}.
-export_type([database/0, connection/0, prepared_statement/0, result/0, sql/0,
type_name/0, statement_type/0,
int8/0, int16/0, int32/0, int64/0,
uint8/0, uint16/0, uint32/0, uint64/0,
idx/0, hugeint/0, uhugeint/0, second/0, time/0, datetime/0
]).
-define(SEC_TO_MICS(S), (S * 1000000)).
-define(MIC_TO_SECS(S), (S / 1000000.0)).
-define(MIN_TO_MICS(S), (S * 60000000)).
-define(HOUR_TO_MICS(S), (S * 3600000000)).
-define(EPOCH_OFFSET, 62167219200000000).
-on_load(init/0).
init() ->
NifName = "educkdb_nif",
NifFileName = case code:priv_dir(educkdb) of
{error, bad_name} -> filename:join("priv", NifName);
Dir -> filename:join(Dir, NifName)
end,
ok = erlang:load_nif(NifFileName, 0).
%%
%% Startup & Configure
%%
%% @doc Open, or create a duckdb database with default options.
-spec open(Filename) -> Result
when Filename :: string(),
Result :: {ok, database()} | {error, _}.
open(Filename) ->
open(Filename, #{}).
%% @doc Open, or create a duckdb file
%%
-spec open(Filename, Options) -> Result
when Filename :: string(),
Options :: map(),
Result :: {ok, database()} | {error, _}.
open(_Filename, _Options) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Connect to the database.
%% Note: It is adviced to use the connection in a single process.
%%
-spec connect(Database) -> Result
when Database :: database(),
Result :: {ok, connection()} | {error, _}.
connect(_Db) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Disconnect from the database.
-spec disconnect(Connection) -> Result
when Connection :: connection(),
Result :: ok | {error, _}.
disconnect(_Connection) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Close the database. All open connections will become unusable.
-spec close(Database) -> Result
when Database :: database(),
Result :: ok | {error, _}.
close(_Db) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc 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:
%% <a href="https://duckdb.org/docs/sql/configuration" target="_parent" rel="noopener">DuckDB Configuration</a>.
-spec config_flag_info() -> map().
config_flag_info() ->
erlang:nif_error(nif_library_not_loaded).
%%
%% Query
%%
%% @doc Query the database. The answer the answer is returned immediately.
-spec query(Connection, Sql) -> Result
when Connection :: connection(),
Sql :: sql(),
Result :: {ok, result()} | {error, _}.
query(_Conn, _Sql) ->
erlang:nif_error(nif_library_not_loaded).
%%
%% Prepared Statements
%%
%% @doc Compile, and prepare a statement for later execution.
-spec prepare(connection(), sql()) -> {ok, prepared_statement()} | {error, _}.
prepare(_Conn, _Sql) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Return the statement type of a prepared statement.
-spec statement_type(PreparedStatement) -> Result
when PreparedStatement :: prepared_statement(),
Result :: statement_type().
statement_type(_PreparedStatement) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Execute a prepared statement. The answer is returned.
-spec execute_prepared(PreparedStatement) -> Result
when PreparedStatement :: prepared_statement(),
Result :: {ok, result()} | {error, _}.
execute_prepared(_PreparedStatement) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Return the parameter name of the prepared statement at the specified index.
-spec parameter_name(PreparedStatement, Index) -> ParameterName
when PreparedStatement :: prepared_statement(),
Index :: idx(),
ParameterName :: binary().
parameter_name(_PreparedStatement, _Index) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Return the parameter type of the prepared statement at the specified index.
-spec parameter_type(PreparedStatement, Index) -> ParameterType
when PreparedStatement :: prepared_statement(),
Index :: idx(),
ParameterType :: type_name().
parameter_type(_PreparedStatement, _Index) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Return the number of parameters in a prepared statement.
-spec parameter_count(PreparedStatement) -> non_neg_integer()
when PreparedStatement :: prepared_statement().
parameter_count(_PreparedStatement) ->
erlang:nif_error(nif_library_not_loaded).
-spec parameter_index(PreparedStatement, Name) -> non_neg_integer()
when PreparedStatement :: prepared_statement(),
Name :: atom() | binary().
parameter_index(_PreparedStatement, _Name) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Return the parameter type of the prepared statement at the specified index.
-spec clear_bindings(PreparedStatement) -> ok | error
when PreparedStatement :: prepared_statement().
clear_bindings(_PreparedStatement) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Bind a boolean to the prepared statement at the specified index.
-spec bind_boolean(PreparedStatement, Index, Boolean) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
Boolean :: boolean(),
BindResponse :: bind_response().
bind_boolean(Statement, Index, true) ->
bind_boolean_intern(Statement, Index, 1);
bind_boolean(Statement, Index, false) ->
bind_boolean_intern(Statement, Index, 0).
-spec bind_boolean_intern(prepared_statement(), idx(), 0..1) -> bind_response().
bind_boolean_intern(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Bind an int8 to the prepared statement at the specified index.
-spec bind_int8(PreparedStatement, Index, Int8) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
Int8 :: int8(),
BindResponse :: bind_response().
bind_int8(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Bind an int16 to the prepared statement at the specified index.
-spec bind_int16(PreparedStatement, Index, Int16) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
Int16 :: int16(),
BindResponse :: bind_response().
bind_int16(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Bind an int32 to the prepared statement at the specified index.
-spec bind_int32(PreparedStatement, Index, Int32) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
Int32 :: int32(),
BindResponse :: bind_response().
bind_int32(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Bind an int64 to the prepared statement at the specified index.
-spec bind_int64(PreparedStatement, Index, Int64) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
Int64 :: int64(),
BindResponse :: bind_response().
bind_int64(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Bind an uint8 to the prepared statement at the specified index.
-spec bind_uint8(PreparedStatement, Index, UInt8) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
UInt8 :: uint8(),
BindResponse :: bind_response().
bind_uint8(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Bind an uint8 to the prepared statement at the specified index.
-spec bind_uint16(PreparedStatement, Index, UInt16) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
UInt16 :: uint16(),
BindResponse :: bind_response().
bind_uint16(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Bind an uint32 to the prepared statement at the specified index.
-spec bind_uint32(PreparedStatement, Index, UInt32) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
UInt32 :: uint32(),
BindResponse :: bind_response().
bind_uint32(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Bind an uint64 to the prepared statement at the specified index.
-spec bind_uint64(PreparedStatement, Index, UInt64) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
UInt64 :: uint64(),
BindResponse :: bind_response().
bind_uint64(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc 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.
-spec bind_float(PreparedStatement, Index, Float) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
Float :: float(),
BindResponse :: bind_response().
bind_float(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc 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.
-spec bind_double(PreparedStatement, Index, Double) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
Double :: float(),
BindResponse :: bind_response().
bind_double(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc 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.
-spec bind_date(PreparedStatement, Index, Date) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
Date :: calendar:date() | integer(),
BindResponse :: bind_response().
bind_date(Stmt, Index, {Y, M, D}=Date) when is_integer(Y) andalso is_integer(M) andalso is_integer(D) ->
bind_date_intern(Stmt, Index, calendar:date_to_gregorian_days(Date));
bind_date(Stmt, Index, Days) when is_integer(Days) ->
bind_date_intern(Stmt, Index, Days).
-spec bind_date_intern(prepared_statement(), idx(), integer()) -> bind_response().
bind_date_intern(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc 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.
-spec bind_time(PreparedStatement, Index, Time) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
Time :: calendar:time() | time() | non_neg_integer(),
BindResponse :: bind_response().
bind_time(Stmt, Index, {H, M, S}) ->
bind_time_intern(Stmt, Index, ?HOUR_TO_MICS(H) + ?MIN_TO_MICS(M) + floor(?SEC_TO_MICS(S)));
bind_time(Stmt, Index, Micros) when is_integer(Micros) ->
bind_time_intern(Stmt, Index, Micros).
bind_time_intern(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc 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.
-spec bind_timestamp(PreparedStatement, Index, TimeStamp) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
TimeStamp :: calendar:datetime() | datetime() | integer(),
BindResponse :: bind_response().
bind_timestamp(Stmt, Index, {MegaSecs, Secs, MicroSecs}) ->
bind_timestamp_intern(Stmt, Index, ?EPOCH_OFFSET + ?SEC_TO_MICS(MegaSecs * 1000000) + ?SEC_TO_MICS(Secs) + MicroSecs);
bind_timestamp(Stmt, Index, {{_, _, _}=Date, {Hour, Minute, Second}}) ->
Mics = ?SEC_TO_MICS(calendar:datetime_to_gregorian_seconds({Date, {Hour, Minute, 0}})),
RemMics = floor(?SEC_TO_MICS(Second)),
bind_timestamp_intern(Stmt, Index, Mics + RemMics);
bind_timestamp(Stmt, Index, Micros) when is_integer(Micros) ->
bind_timestamp_intern(Stmt, Index, Micros).
bind_timestamp_intern(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
% @doc 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.
-spec bind_varchar(PreparedStatement, Index, IOData) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
IOData :: iodata(),
BindResponse :: bind_response().
bind_varchar(_Stmt, _Index, _Value) ->
erlang:nif_error(nif_library_not_loaded).
% @doc Bind a null value to the prepared statement at the specified index.
-spec bind_null(PreparedStatement, Index) -> BindResponse
when PreparedStatement :: prepared_statement(),
Index :: idx(),
BindResponse :: bind_response().
bind_null(_Stmt, _Index) ->
erlang:nif_error(nif_library_not_loaded).
%%
%% Results
%%
%% @doc Get all data chunks from a query result.
-spec get_chunks(QueryResult) -> DataChunks
when QueryResult :: result(),
DataChunks :: list(data_chunk()).
get_chunks(_Result) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Fetches a data chunk from a result. The function should be called
%% repeatedly until the result is exhausted.
-spec fetch_chunk(QueryResult) -> DataChunk | '$end'
when QueryResult :: result(),
DataChunk :: data_chunk().
fetch_chunk(_Result) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Get the column names from the query result.
-spec column_names(QueryResult) -> Names
when QueryResult :: result(),
Names :: list(binary()).
column_names(_Result) ->
erlang:nif_error(nif_library_not_loaded).
%%
%% Chunks
%%
%% @doc Return the number of columns in the data chunk.
-spec chunk_column_count(DataChunk) -> ColumnCount
when DataChunk :: data_chunk(),
ColumnCount :: uint64().
chunk_column_count(_Chunk) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Get the column types of the chunk
%% [todo] spec..
chunk_column_types(_Chunk) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Get the columns data of the chunk
%% [todo] spec
chunk_columns(_Chunk) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Return the number of tuples in th data chunk.
-spec chunk_size(DataChunk) -> TupleCount
when DataChunk :: data_chunk(),
TupleCount :: uint64().
chunk_size(_Chunk) ->
erlang:nif_error(nif_library_not_loaded).
%%
%% Appender Interface
%%
%% @doc Create an appender. Appenders allow for high speed bulk insertions into the database. See
%% <a href="https://duckdb.org/docs/data/appender">DuckDB Appender</a> for more information.
-spec appender_create(Connection, Schema, Table) -> Result
when Connection :: connection(),
Schema :: undefined | binary(),
Table :: binary,
Result :: {ok, appender()} | {error, _}.
appender_create(_Connection, _Schema, _Table) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a boolean value to the current location in the row.
-spec append_boolean(Appender, Boolean) -> AppendResponse
when Appender :: appender(),
Boolean :: boolean(),
AppendResponse :: append_response().
append_boolean(Appender, true) ->
append_boolean_intern(Appender, 1);
append_boolean(Appender, false) ->
append_boolean_intern(Appender, 0).
-spec append_boolean_intern(appender(), int32()) -> append_response().
append_boolean_intern(_Appender, _Integer) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a tinyint to the current location in the row.
-spec append_int8(Appender, TinyInt) -> AppendResponse
when Appender :: appender(),
TinyInt :: int8(),
AppendResponse :: append_response().
append_int8(_Appender, _Integer) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a smallint to the current location in the row.
-spec append_int16(Appender, SmallInt) -> AppendResponse
when Appender :: appender(),
SmallInt :: int16(),
AppendResponse :: append_response().
append_int16(_Appender, _Integer) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append an integer (32 bit) to the current location in the row.
-spec append_int32(Appender, Integer) -> AppendResponse
when Appender :: appender(),
Integer :: int32(),
AppendResponse :: append_response().
append_int32(_Appender, _Integer) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a bigint to the current location in the row.
-spec append_int64(Appender, BigInt) -> AppendResponse
when Appender :: appender(),
BigInt :: int64(),
AppendResponse :: append_response().
append_int64(_Appender, _Integer) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a utinyint to the current location in the row.
-spec append_uint8(Appender, UTinyInt) -> AppendResponse
when Appender :: appender(),
UTinyInt :: uint8(),
AppendResponse :: append_response().
append_uint8(_Appender, _Integer) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a usmallint to the current location in the row.
-spec append_uint16(Appender, USmallInt) -> AppendResponse
when Appender :: appender(),
USmallInt :: uint16(),
AppendResponse :: append_response().
append_uint16(_Appender, _Integer) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append an unsigned integer (32 bit) to the current location in the row.
-spec append_uint32(Appender, UInteger) -> AppendResponse
when Appender :: appender(),
UInteger :: uint32(),
AppendResponse :: append_response().
append_uint32(_Appender, _Integer) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a ubigint to the current location in the row.
-spec append_uint64(Appender, UBigInt) -> AppendResponse
when Appender :: appender(),
UBigInt :: uint64(),
AppendResponse :: append_response().
append_uint64(_Appender, _Integer) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc 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.
-spec append_float(Appender, Float) -> AppendResponse
when Appender :: appender(),
Float :: float(),
AppendResponse :: append_response().
append_float(_Appender, _Integer) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a double to the current location in the row. Note: duckdb double's
%% are the same as erlang floats.
-spec append_double(Appender, Double) -> AppendResponse
when Appender :: appender(),
Double :: float(),
AppendResponse :: append_response().
append_double(_Appender, _Integer) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a time to the current location in the row.
-spec append_time(Appender, Time) -> AppendResponse
when Appender :: appender(),
Time :: calendar:time() | time() | non_neg_integer(),
AppendResponse :: append_response().
append_time(Appender, {H, M, S}) ->
append_time_intern(Appender, ?HOUR_TO_MICS(H) + ?MIN_TO_MICS(M) + floor(?SEC_TO_MICS(S)));
append_time(Appender, Micros) when is_integer(Micros) ->
append_time_intern(Appender, Micros).
append_time_intern(_Appender, _Time) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a data to the current location in the row.
-spec append_date(Appender, Date) -> AppendResponse
when Appender :: appender(),
Date :: calendar:date() | integer(),
AppendResponse :: append_response().
append_date(Appender, {Y, M, D}=Date) when is_integer(Y) andalso is_integer(M) andalso is_integer(D) ->
append_date_intern(Appender, calendar:date_to_gregorian_days(Date));
append_date(Appender, Days) when is_integer(Days) ->
append_date_intern(Appender, Days).
append_date_intern(_Appender, _Date) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a timestamp to the current location in the row.
-spec append_timestamp(Appender, Timestamp) -> AppendResponse
when Appender :: appender(),
Timestamp :: calendar:datetime() | erlang:timestamp() | datetime() | integer(),
AppendResponse :: append_response().
append_timestamp(Appender, {MegaSecs, Secs, MicroSecs}) ->
append_timestamp_intern(Appender, ?EPOCH_OFFSET + ?SEC_TO_MICS(MegaSecs * 1000000) + ?SEC_TO_MICS(Secs) + MicroSecs);
append_timestamp(Appender, {{_, _, _}=Date, {Hour, Minute, Second}}) ->
Millies = ?SEC_TO_MICS(calendar:datetime_to_gregorian_seconds({Date, {Hour, Minute, 0}})),
RemMillies = floor(?SEC_TO_MICS(Second)),
append_timestamp_intern(Appender, Millies + RemMillies);
append_timestamp(Appender, Micros) when is_integer(Micros) ->
append_timestamp_intern(Appender, Micros).
append_timestamp_intern(_Appender, _Timestamp) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a varchar to the current location in the row.
-spec append_varchar(Appender, IOData) -> AppendResponse
when Appender :: appender(),
IOData :: iodata(),
AppendResponse :: append_response().
append_varchar(_Appender, _IOData) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Append a null value to the current location in the row.
-spec append_null(Appender) -> AppendResponse
when Appender :: appender(),
AppendResponse :: append_response().
append_null(_Appender) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Finalize the current row, and start a new one.
-spec appender_end_row(Appender) -> AppendResponse
when Appender :: appender(),
AppendResponse :: append_response().
appender_end_row(_Appender) ->
erlang:nif_error(nif_library_not_loaded).
%% @doc Flush the appender to the table, forcing the cache of the appender to be cleared
%% and the data to be appended to the base table.
-spec appender_flush(Appender) -> AppendResult
when Appender :: appender(),
AppendResult :: append_response().
appender_flush(_Appender) ->
erlang:nif_error(nif_library_not_loaded).
%%
%% Higher Level API
%%
result_extract(Result) ->
case fetch_chunk(Result) of
'$end' ->
{ok, [], []};
Chunk ->
Names = column_names(Result),
Types = chunk_column_types(Chunk),
Info = column_info(Names, Types),
Rows = chunk_rows(Chunk, Result, []),
{ok, Info, Rows}
end.
column_info(Names, Types) ->
column_info(Names, Types, []).
column_info([], _, Acc) ->
lists:reverse(Acc);
column_info([N|T], undefined, Acc) ->
column_info(T, undefined, [#column{name=N}|Acc]);
column_info([Name|RestNames], [Type|RestTypes], Acc) ->
column_info(RestNames, RestTypes, [#column{name=Name, type=Type}|Acc]).
chunk_rows('$end', _Result, Rows) ->
lists:reverse(lists:flatten(Rows));
chunk_rows(Chunk, Result, Rows) ->
R = lists:reverse(
lists:map(fun list_to_tuple/1,
transpose(
chunk_columns(Chunk)))),
chunk_rows(fetch_chunk(Result), Result, [R | Rows]).
%% @doc Do a simple sql query without parameters, and retrieve the result from the
%% first data chunk.
-spec squery(Connection, Sql) -> Result
when Connection :: connection(),
Sql :: sql(),
Result :: {ok, [ named_column() ]} | {error, _}.
squery(Connection, Sql) ->
case query(Connection, Sql) of
{ok, Result} ->
result_extract(Result);
{error, _}=E ->
E
end.
%% @doc Execute a prepared statement, and retrieve the first result from the first
%% data chunk.
-spec execute(PreparedStatement) -> Result
when PreparedStatement :: prepared_statement(),
Result :: {ok, [ named_column() ]} | {error, _}.
execute(Stmt) ->
case execute_prepared(Stmt) of
{ok, Result} ->
result_extract(Result);
{error, _}=E ->
E
end.
%%
%% Utilities
%%
transpose([[]|_]) -> [];
transpose(M) ->
[ lists:map(fun hd/1, M) | transpose(lists:map(fun tl/1, M))].
%% @doc Convert a duckdb hugeint record to an erlang integer.
-spec hugeint_to_integer(Hugeint) -> Integer
when Hugeint :: hugeint(),
Integer :: integer().
hugeint_to_integer(#hugeint{upper=Upper, lower=Lower}) ->
(Upper bsl 64) bor Lower.
%% @doc Convert an erlang integer to a DuckDB hugeint.
%%
%% For more information on DuckDB numeric types: See <a href="https://duckdb.org/docs/sql/data_types/numeric" target="_parent" rel="noopener">DuckDB Numeric Data Types</a>.
-spec integer_to_hugeint(Integer) -> Hugeint
when Integer :: integer(),
Hugeint :: hugeint().
integer_to_hugeint(Int) ->
#hugeint{upper=(Int bsr 64), lower=(Int band 16#FFFFFFFFFFFFFFFF)}.
%% @doc Convert a duckdb uhugeint record to an erlang integer.
-spec uhugeint_to_integer(UHugeint) -> Integer
when UHugeint :: uhugeint(),
Integer :: integer().
uhugeint_to_integer(#uhugeint{upper=Upper, lower=Lower}) ->
(Upper bsl 64) bor Lower.
-spec integer_to_uhugeint(NonNegInteger) -> UHugeint
when NonNegInteger :: non_neg_integer(),
UHugeint :: uhugeint().
integer_to_uhugeint(Int) when Int >= 0 ->
#uhugeint{upper=(Int bsr 64), lower=(Int band 16#FFFFFFFFFFFFFFFF)}.
%% @doc Convert a binary represented UUID to a printable hex representation.
uuid_binary_to_uuid_string(Bin) ->
Formatted = io_lib:format("~8.16.0b-~4.16.0b-~4.16.0b-~2.16.0b~2.16.0b-~12.16.0b", uuid_unpack(Bin)),
erlang:iolist_to_binary(Formatted).
%% @doc Convert a printable UUID to a binary representation.
uuid_string_to_uuid_binary(U)->
uuid_string_to_uuid_binary1(U, <<>>).
uuid_string_to_uuid_binary1(<<>>, Acc) -> Acc;
uuid_string_to_uuid_binary1(<<$-, Rest/binary>>, Acc) ->
uuid_string_to_uuid_binary1(Rest, Acc);
uuid_string_to_uuid_binary1(<<A, B, Rest/binary>>, Acc) ->
Int = list_to_integer([A,B], 16),
uuid_string_to_uuid_binary1(Rest, <<Acc/binary, Int>>).
%uuid_pack(TL, TM, THV, CSHR, CSL, N) ->
% <<UUID:128>> = <<TL:32, TM:16, THV:16, CSHR:8, CSL:8, N:48>>,
% UUID.
uuid_unpack(<<TL:32, TM:16, THV:16, CSHR:8, CSL:8, N:48>>) ->
[TL, TM, THV, CSHR, CSL, N].
