GitHub

API Reference

OhMyCH.HttpConfig — Type
HttpConfig

Defines the configuration for the HTTP connection to the database.

Fields

  • url::String: Database server URL.
  • database::String: Name of the database.
  • user::String: Username for authentication.
  • password::String: Password for authentication.
  • verify_ssl::Bool: Verify SSL certificates for HTTPS.
source
OhMyCH.HttpClient — Type
HttpClient

Defines an HTTP client to connect to the database.

Fields

  • config::HttpConfig: Connection configuration, including URL, database name, and credentials.
  • curl_client::CurlClient: Handles HTTP communication with the database server.
source
OhMyCH.ohmych_connect — Function
ohmych_connect(url::String, database::String, user::String, password::String) -> HttpClient
ohmych_connect(config::HttpConfig) -> HttpClient
ohmych_connect(f::Function, args...) -> HttpClient

Creates an HttpClient instance to connect to a database. Once the connection is no longer needed, it must be closed using the close method. The method that takes a function f as the first argument will close the connection automatically.

Keyword arguments

  • verify_ssl::Bool: Whether to verify the SSL certificate (default: true).
source
Base.isopen — Function
isopen(client::HttpClient) -> Bool

Checks that the client is connected to the database.

source
Base.close — Function
close(client::HttpClient)

Closes the client connection to the database.

source

Database requests

OhMyCH.execute — Function
execute(client::HttpClient, query::String [, parameters::NamedTuple]; options...) -> Nothing

Sends a query to the database using the HttpClient client. Values that need to be substituted into the query can be specified as parameters (see more in Queries with parameters).

Info

This type of request does not imply the return of any result (Fire and Forget).

Keyword arguments

  • use_compression::Bool: Flag for enabling data compression (default: true). See more in Content encoding section.
  • max_execution_time::Int: Maximum allowed execution time in seconds (default: 60 seconds).
  • options...: Additional options passed to the query execution function.

Examples

julia> client = ohmych_connect("http://127.0.0.1:8123", "database", "username", "password");

julia> employees_query = """
       CREATE TABLE IF NOT EXISTS employees
       (
            name     String
           ,age      Int32
           ,position String
           ,salary   Float64
       )
       ENGINE = MergeTree()
       ORDER BY name
       """;

julia> execute(client, employees_query)
source
OhMyCH.insert — Function
insert(client::HttpClient, query::String, values::Vector; options...) -> Nothing

Sends a query to insert values into the database using the HttpClient client

Info

This type of request does not imply the return of any result (Fire and Forget).

Keyword arguments

  • chunk_size::Int: Specifies the approximate size (in bytes) of one chunk of data being sent (default: 256 * 1024 bytes).
  • use_compression::Bool: Flag for enabling data compression (default: true). See more in Content encoding section.
  • max_execution_time::Int: Maximum allowed execution time in seconds (default: 60 seconds).
  • options...: Additional options passed to the query execution function.

Examples

julia> client = ohmych_connect("http://127.0.0.1:8123", "database", "username", "password");

julia> insert(client, "INSERT INTO employees (name, age, position, salary)", [
    (name = "Alice", age = Int32(29), position = "Developer", salary = 75000.5),
    (name = "Bob", age = Int32(35), position = "Manager", salary = 92000.75),
    (name = "Clara", age = Int32(28), position = "Designer", salary = 68000.0),
    (name = "David", age = Int32(40), position = "Developer", salary = 81000.3),
])
source
OhMyCH.query — Function
query(client::HttpClient, query::String [, parameters::NamedTuple]; options...) -> RowBinaryWithNamesAndTypes

Sends a query to the database using the HttpClient client. Values that need to be substituted into the query can be specified as parameters (see more in Queries with parameters).

Info

This type of query involves returning the result from the database. The returned data is represented as a RowBinaryWithNamesAndTypes object.

Keyword arguments

  • use_compression::Bool: Flag for enabling data compression (default: true). See more in Content encoding section.
  • max_execution_time::Int: Maximum allowed execution time in seconds (default: 60 seconds).
  • options...: Additional options passed to the query execution function.

See also eachrow, collect.

Examples

julia> client = ohmych_connect("http://127.0.0.1:8123", "database", "username", "password");

julia> query(client, "SELECT * FROM employees")
RowBinaryWithNamesAndTypes(161-bytes):
 name::String
 age::Int32
 position::String
 salary::Float64
source
OhMyCH.insert_binary — Function
insert_binary(client::HttpClient, query::String, values::RowBinary; options...) -> RowBinary

Works similarly to the insert method, except that the sending data must be a RowBinary object.

Tip

This method is effective when sending small portions of data frequently. Intended use in conjunction with query_binary for fast data transfer between databases.

Examples

julia> client = ohmych_connect("http://127.0.0.1:8123", "database", "username", "password");

julia> binary_data = query_binary(client, "SELECT * FROM employees")
RowBinary(107-bytes)

julia> insert_binary(client, "INSERT INTO another_employees", binary_data)
source
OhMyCH.query_binary — Function
query_binary(client::HttpClient, query::String [, parameters::NamedTuple]; options...) -> RowBinary

Works similarly to the query method, except that the retrieved data is represented as a RowBinary object.

Tip

This method is effective when requesting small portions of data frequently, since the response does not include information about names and data types. However, in this case, the user will be required to describe the column types and names themselves using his own type T.

See also eachrow, collect.

Examples

julia> client = ohmych_connect("http://127.0.0.1:8123", "database", "username", "password");

julia> query_binary(client, "SELECT * FROM employees")
RowBinary(107-bytes)
source

Row iteration

Base.eachrow — Function
eachrow(binary::RowBinaryWithNamesAndTypes) -> BinaryToRowIter

Creates a new iterator BinaryToRowIter that determines column types and their names from binary object. The elements of such an iterator are NamedTuple objects.

Examples

julia> client = ohmych_connect("http://127.0.0.1:8123", "database", "username", "password");

julia> employees = query(client, "SELECT * FROM employees");

julia> for user in eachrow(employees)
           println(user)
       end
(name = "Alice", age = 29, position = "Developer", salary = 75000.5)
(name = "Bob", age = 35, position = "Manager", salary = 92000.75)
(name = "Clara", age = 28, position = "Designer", salary = 68000.0)
(name = "David", age = 40, position = "Developer", salary = 81000.3)
source
eachrow(::Type{T}, binary::RowBinaryResult) -> BinaryToRowIter

Creates a new iterator BinaryToRowIter that uses fields of type T to determine column types. The elements of such an iterator are objects of type T.

Examples

julia> client = ohmych_connect("http://127.0.0.1:8123", "database", "username", "password");

julia> employees = query_binary(client, "SELECT * FROM employees");

julia> struct Employee
           name::String
           age::Int32
           position::String
           salary::Float64
       end

julia> for employee in eachrow(Employee, employees)
           println(employee)
       end
Employee("Alice", 29, "Developer", 75000.5)
Employee("Bob", 35, "Manager", 92000.75)
Employee("Clara", 28, "Designer", 68000.0)
Employee("David", 40, "Developer", 81000.3)
source
Base.collect — Function
collect(binary::RowBinaryWithNamesAndTypes) -> Vector{NamedTuple}
collect(::Type{T}, binary::RowBinaryResult) -> Vector{T}

Works similarly to the eachrow method, but instead of creating an iterator, it returns all values from the binary representation of the data.

Warning

If you don't need all the values at once, it's preferable to iterate over the rows using the eachrow method.

Examples

julia> client = ohmych_connect("http://127.0.0.1:8123", "database", "username", "password");

julia> employees = query(client, "SELECT * FROM employees");

julia> collect(employees)
4-element Vector{NamedTuple{(:name, :age, :position, :salary), Tuple{String,Int32,String,Float64}}}:
 (name = "Alice", age = 29, position = "Developer", salary = 75000.5)
 (name = "Bob", age = 35, position = "Manager", salary = 92000.75)
 (name = "Clara", age = 28, position = "Designer", salary = 68000.0)
 (name = "David", age = 40, position = "Developer", salary = 81000.3)
source

Column types

Most of the ClickHouse column types are the same as the Julia base types.

ClickHouse TypeJulia Type
BoolBool
Int8-128, UInt8-128Int8-128, UInt8-128
Float32, Float64Float32, Float64
Decimal(P,S)Decimal{P,S}
StringString
FixedString(N)FixedString{N}
DateDate
DateTimeDateTime
DateTime64NanoDate
Enum8, Enum16UInt8, UInt16
UUIDUUID
IPv4, IPv6IPv4, IPv6
Array(T)AbstractVector{T}
Tuple(T1, T2, ...)Tuple
Map(K, V)AbstractDict{K,V}
LowCardinality(T)T
Nullable(T)Union{Nothing,T}

However, some types had to be implemented independently.

Decimal

OhMyCH.Decimal — Type
Decimal{P,S} <: AbstractFloat

A type that represents a fixed-precision decimal number with precision P and scale S. Precision P is a total number of digits in the number (including digits before and after the decimal point). Scale S is a number of digits after the decimal point.

source
OhMyCH.Decimal — Method
Decimal{P,S}(value::Union{Real,AbstractString})

Constructs a Decimal with precision P and scale S from a value.

Examples

julia> Decimal{5,2}(123.45)
Decimal{5,2}(123.45)

julia> Decimal{5,2}("123.45")
Decimal{5,2}(123.45)

julia> Decimal{5,2}(123456.0)
ERROR: ArgumentError: Decimal value 123456.0 exceeds limits for Decimal{P=5,S=2}. Max allowed: ±999.99.
source
OhMyCH.Decimal — Method
Decimal{P,S}([sign::Integer, ] significand::Integer, exponent::Integer)

Constructs a Decimal with precision P and scale S from its components:

  • sign: The sign of the decimal (+1 or -1).
  • significand: The integer part of the number (absolute value).
  • exponent: The base-10 exponent.

Examples

julia> Decimal{5,2}(12345, -2)
Decimal{5,2}(123.45)

julia> Decimal{5,2}(-1, 12345, -3)
Decimal{5,2}(-12.345)

julia> Decimal{5,2}(123456, -2)
ERROR: ArgumentError: Decimal value 1234.56 exceeds limits for Decimal{P=5,S=2}. Max allowed: ±999.99.
source

FixedString

OhMyCH.FixedString — Type
FixedString{N} <: AbstractString

A string type with a fixed maximum size N.

Fields

  • data::String: The string data that is constrained by the fixed size N.
source
OhMyCH.FixedString — Method
FixedString{N}(x::String)

Constructs a FixedString object with a fixed maximum size N from the given string x.

Examples

julia> FixedString{10}("Hello")
FixedString{10}("Hello")

julia> FixedString{3}("Hello")
ERROR: ArgumentError: Input string is longer than 3 bytes (5)
source

Exceptions

OhMyCH.CHServerException — Type
CHServerException <: OhMyCHException

Raised when the ClickHouse server returns an error response while processing a query.

Fields

  • code::ErrorCodes: An error code indicating the type of database error.
  • message::String: A descriptive message providing details about the error.

See also ErrorCodes.

source
OhMyCH.CHClientException — Type
CHClientException <: OhMyCHException

Represents an error that occurs during HTTP communication with the ClickHouse database.

Fields

  • message::String: A descriptive message providing details about the error.
source