QuestDBOperators

const ColumnName = Union{Symbol, String}

The column name can be specified as a symbol or as a string

const SymbolColumnValue = Union{Symbol, String}

A symbol column can take values that are either a Symbol or a String

const supportedTypes::Vector{Type} = [Integer, AbstractFloat, AbstractString, Symbol, Dates.DateTime, 
                                     Dates.Date, Char, UUID]

A list of supported types

const COMMA = ","

A constant referencing a comma - ','

const SPACE_CHARACTER = ' '

A constant referencing the space character

const RETURN_CHARACTER = '\n'

A constant referencing the return character

const EQUALS_CHARACTER = '='

A constant referencing the equals character.

const UNSUPPORTED_CHARACTERS = ['?', '.' , ',' , ''' , '"' , '\' , '/', ':' , '(' , ')' , '+' , '-' , '*' , '%' , '~' , ' ' , '']

The list of unsupported characters for table & column names

table(sender::Sender, name::T)::Sender where {T <: ColumnName}

Table definition function for an ILP entry. Adds a table name to the sender's buffer and returns the sender with an updated buffer.

The ColumnName is Union{Symbol, String}

Example

julia> table(sender, :readings)
## sender with table readings

symbol(sender::Sender, symbol::Pair{T, V})::Sender where {T <: ColumnName, V <: SymbolColumnValue}

Symbol definition function for an ILP entry. Adds a symbol (tag_set) to the sender's buffer and returns the sender with an updated buffer. The symbol argument is a Pair{T, V} where T <: ColumnName and V <: SymbolColumnValue

This requires that a table has already been added to the sender's buffer.

The ColumnName is Union{Symbol, String}

The SymbolColumnValue is Union{Symbol, String}

Example

julia> symbol(sender, :make => :Omron)
## sender with symbol make=Omron

writeSymbol(queryString::String, symbol::Pair{T, V})::String where {T <: ColumnName, V <: SymbolColumnValue}

Function used to create append a symbol when constructing an ILP string. The symbol argument is a Pair{T, V} where T <: ColumnName and V <: SymbolColumnValue

Also asserts that QuestDB unsupported column name characters result in exception propagation

The ColumnName is Union{Symbol, String}

The SymbolColumnValue is Union{Symbol, String}

Example

julia> writeSymbol("", :make => :Omron)
make=Omron 

IntegerColumn(sender::Sender, data::Pair{T, V})::Sender where {T <: ColumnName, V <: Union{Integer, Nothing}}

IntegerColumn definition function for an ILP entry. Adds a field of type integer to the sender's buffer and returns the sender with an updated buffer. The data argument is a Pair{T, V} where T <: ColumnName and V <: Union{Integer, Nothing}

This requires that a table has already been added to the sender's buffer.

The ColumnName is Union{Symbol, String}

All Integer subtypes are supported: Bool, BigInt, Int128, Int64, Int32, Int16, Int8, UInt128, UInt64, UInt32, UInt16, UInt8

Example

julia> IntegerColumn(sender, :count => 12)
## sender with field count=12

If nothing is passed as the second part of the part of the data pair, V, this column won't be written

Example

julia> IntegerColumn(sender, :count => nothing)
## sender without an updated buffer

writeFieldColumn(queryString::String, data::Pair{T, V})::String where {T <:ColumnName, V <: Any}

Function used to append any other field to the ILP entry. If the type of V is nothing, the passed field will not be written to the queryString which is eventually appended to the sender's buffer.

A check for unsupported column characters is also performed.

Example

julia> writeFieldColumn(sender, :count => 15)
## sender with field count=12

Example

julia> IntegerColumn(sender, :count => nothing)
## sender without an updated buffer

checkUnsupportedCharacters(subject::T, exception::Type{E}) where {T <: ColumnName, E <: QuestDBClientException}

Asserts that only supported column name characters pass this evaluation. Any unsupported character results in throwing a QuestDBClientException.

Unsupported characters include: ['?', '.' , ',' , ''' , '"' , '\' , '/', ':' , '(' , ')' , '+' , '-' , '*' , '%' , '~' , ' ' , '']

BoolColumn(sender::Sender, data::Pair{T, Bool})::Sender where {T <: ColumnName}

BoolColumn definition function for an ILP entry. Adds a field of type bool to the sender's buffer and returns the sender with an updated buffer. The data argument is a Pair{T, Bool} where T <: ColumnName.

This requires that a table has already been added to the sender's buffer.

The ColumnName is Union{Symbol, String}

Example

julia> BoolColumn(sender, :present => true)
## sender with field present=true

FloatColumn(sender::Sender, data::Pair{T, V})::Sender where {T <: ColumnName, V <: Union{AbstractFloat, Nothing}}

FloatColumn definition function for an ILP entry. Adds a field of type float to the sender's buffer and returns the sender with an updated buffer. The data argument is a Pair{T, V} where T <: ColumnName and V <: Union{AbstractFloat, Nothing}

This requires that a table has already been added to the sender's buffer.

The ColumnName is Union{Symbol, String}

All AbstractFloat subtypes are supported: BigFloat, Float64, Float32, Float16

Example

julia> FloatColumn(sender, :tempareture => 29.4)
## sender with field tempareture=29.4

If nothing is passed as the second part of the part of the data pair, V, this column won't be written

Example

julia> FloatColumn(sender, :tempareture => nothing)
## sender without an updated buffer

StringColumn(sender::Sender, data::Pair{T, V})::Sender where {T <: ColumnName, V <: Union{AbstractString, Nothing}}

StringColumn definition function for an ILP entry. Adds a field of type string to the sender's buffer and returns the sender with an updated buffer. The data argument is a Pair{T, V} where T <: ColumnName and V <: Union{AbstractString, Nothing}

This requires that a table has already been added to the sender's buffer.

The ColumnName is Union{Symbol, String}

All AbstractString subtypes are supported: Core.Compiler.LazyString, InlineStrings.InlineString, LaTeXStrings.LaTeXString, LazyString, String, SubString, SubstitutionString, Test.GenericString

Example

julia> StringColumn(sender, :city => "Nairobi")
## sender with field city=Nairobi

If nothing is passed as the second part of the part of the data pair, V, this column won't be written

Example

julia> StringColumn(sender, :city => nothing)
## sender without an updated buffer

CharColumn(sender::Sender, data::Pair{T, V})::Sender where {T <: ColumnName, V <: Union{Char, Nothing}}

CharColumn definition function for an ILP entry. Adds a field of type string to the sender's buffer and returns the sender with an updated buffer. The data argument is a Pair{T, V} where T <: ColumnName and V <: Union{Char, Nothing}

This requires that a table has already been added to the sender's buffer.

The ColumnName is Union{Symbol, String}

Example

julia> CharColumn(sender, :region => 'A')
## sender with field region=A

If nothing is passed as the second part of the part of the data pair, V, this column won't be written

Example

julia> CharColumn(sender, :region => nothing)
## sender without an updated buffer

DateTimeColumn(sender::Sender, data::Pair{T, V})::Sender where {T <: ColumnName, V <: Union{DateTime, Nothing}}

DateTimeColumn definition function for an ILP entry. Adds a field of type string to the sender's buffer and returns the sender with an updated buffer. The data argument is a Pair{T, V} where T <: ColumnName and V <: Union{DateTime, Nothing}

The DateTime is converted to milliseconds since UNIXEPOCH

This is not the record's designated timestamp field but another field whose value is a timestamp.

This requires that a table has already been added to the sender's buffer.

The ColumnName is Union{Symbol, String}

Example

julia> DateTimeColumn(sender, :pick_up_date => now())
## sender with field pick_up_date=1680990219992

If nothing is passed as the second part of the part of the data pair, V, this column won't be written

Example

julia> DateTimeColumn(sender, :pick_up_date => nothing)
## sender without an updated buffer

DateColumn(sender::Sender, data::Pair{T, V})::Sender where {T <: ColumnName, V <: Union{Date, Nothing}}

DateColumn definition function for an ILP entry. Adds a field of type string to the sender's buffer and returns the sender with an updated buffer. The data argument is a Pair{T, V} where T <: ColumnName and V <: Union{Date, Nothing}

The Date is converted to milliseconds since UNIXEPOCH

This requires that a table has already been added to the sender's buffer.

The ColumnName is Union{Symbol, String}

Example

julia> DateColumn(sender, :collection_date => Date(2023, 4, 8))
## sender with field collection_date=1680912000000

If nothing is passed as the second part of the part of the data pair, V, this column won't be written

Example

julia> DateColumn(sender, :collection_date => nothing)
## sender without an updated buffer

UUIDColumn(sender::Sender, data::Pair{T, V})::Sender where {T <: ColumnName, V <: Union{UUID, Nothing}}

UUIDColumn definition function for an ILP entry. Adds a field of type string to the sender's buffer and returns the sender with an updated buffer. The data argument is a Pair{T, V} where T <: ColumnName and V <: Union{UUID, Nothing}

This requires that a table has already been added to the sender's buffer.

The ColumnName is Union{Symbol, String}

Example

julia> using UUIDs
julia> using Random
julia> rng = MersenneTwister(1234);
julia> u4 = uuid4(rng);
julia> UUIDColumn(sender, :user_id => u4)
## sender with field user_id=7a052949-c101-4ca3-9a7e-43a2532b2fa8

If nothing is passed as the second part of the part of the data pair, V, this column won't be written

Example

julia> UUIDColumn(sender, :user_id => nothing)
## sender without an updated buffer

UUIDColumn(sender::Sender, data::Pair{T, V})::Sender where {T <: ColumnName, V <: Union{String, Nothing}}

UUIDColumn definition function for an ILP entry. Adds a field of type string to the sender's buffer and returns the sender with an updated buffer. The data argument is a Pair{T, V} where T <: ColumnName and V <: Union{String, Nothing}

Takes in the UUID as a string.

This requires that a table has already been added to the sender's buffer.

The ColumnName is Union{Symbol, String}

Example

julia> UUIDColumn(sender, :user_id => "7a052949-c101-4ca3-9a7e-43a2532b2fa8")
## sender with field user_id=7a052949-c101-4ca3-9a7e-43a2532b2fa8

If nothing is passed as the second part of the part of the data pair, V, this column won't be written

Example

julia> UUIDColumn(sender, :user_id => nothing)
## sender without an updated buffer

At(sender::Sender, timestamp::DateTime)::Nothing

At column definition function for an ILP entry. This is the designated timestamp field.

The timestamp is converted to nanoseconds since UNIXEPOCH

This requires that a table has already been added to the sender's buffer.

Upon setting this field, the hasFields and hasTable properties of the sender are set to false. This also marks the end of the record with a '\n'.

Serves as a terminal definition of a record. Should always be defined last.

Example

julia> At(sender, now())
## sender with field 1680993284179000000\n

AtNow(sender::Sender)::Nothing

This requires that a table has already been added to the sender's buffer.

Resolves to: At(sender, now())

Example

julia> AtNow(sender)
## sender with field 1680993284179000000\n

Source(sender::Sender, df::DataFrame, table::TT; 
       at::T = "", symbols::Vector{V} = [])::Sender where {TT<: ColumnName, T <: ColumnName, V <: ColumnName}

Takes in a DataFrame object and creates ILP insert statement for each row element.

Arguments

- `sender::Sender` : QUestDBClient sender object
- `df::DataFrame`: the `DataFrame` that serves as the source of the data
- `table::TT where {TT <: ColumnName}` : the name of the `table`
- `at::T where {T <: ColumnName}` : the column that has timestamp values that server as the designated timestamp
- `symbols::Vector{V} where {V <: ColumnName}`: the list of column names whose columns serve as `tag_set` values for an ILP record

The ColumnName is Union{Symbol, String}

The table specification is a requirement.

at argument is used to specify the column header of the column in the DataFrame that will serve as the designated timestamp field. The column should have values of type DateTime and will be converted to nanoseconds upon when converted to an ILP record. If the at is not specified, the current time will be added to each ILP record.

symbols argument specifies a vector of columns headers of DataFrame columns that serve as the tag_set in the ILP statement. If symbols are not specified, then no tag_set fields will be part of the ILP statement.

• Assuming df below is the DataFrame above:

Example

julia> using DataFrames
julia> df = DataFrame(city=["London", "Nairobi"], make=[:Omron, :Honeywell], temperature=[29.4, 24.0], humidity=[0.334, 0.51]);
julia> Source(sender, df, :readings, symbols=[:city, :make]);
## sender with 2 ILP records from the 2 rows in the DataFrame

• An example with the at field specified.

Example

julia> using DataFrames
julia> df = DataFrame(city=["London", "Nairobi"], make=[:Omron, :Honeywell], temperature=[29.4, 24.0], 
            humidity=[0.334, 0.51], collection_time=["2023-04-10T13:09:31Z", "2023-04-10T13:09:42Z"]);
julia> using Dates
julia> date_format = dateformat"y-m-dTH:M:SZ";
julia> df[!, :collection_time] = DateTime.(df[:, :collection_time], date_format);
julia> Source(sender, df, :readings, symbols = [:city, :make], at = :collection_time);
## sender with 2 ILP records from the 2 rows in the DataFrame

writeRowEnty!(sender::Sender, dataType::Type, data::Pair{T, V})::Sender where {T <: ColumnName, V <: Any}

A helper function to build ILP records from a dataframe based on the column types.