@spec new(Keyword.t()) :: Req.Request.t()

Builds a new %Req.Request{} for ClickHouse requests.

Options

This function can receive any option that Req.new/1 accepts, plus the ones described below.

To set a new endpoint, use the :base_url option from Req. It is by default "http://localhost:8123".

• :format - Optional. The format of the response. Default is :tsv. This option accepts :tsv, :csv, :json, :explorer and :adbc as atoms.

  It also accepts all formats described in the https://clickhouse.com/docs/en/interfaces/formats page. Use plain strings for these formats.

  The :adbc and :explorer formats are special, and will build an Result struct in case the required dependency is installed.

• :database - Optional. The database to use in the queries. Default is nil.

Examples

After setting a default database, one can make queries using query/4 and query!/4:

iex> req = ReqCH.new(database: "system")
iex> ReqCH.query!(req, "SELECT number + 1 FROM numbers LIMIT 3").body
"1\n2\n3\n"

In case the server needs authentication, it's possible to use Req options for that.

iex> req = ReqCH.new(base_url: "http://example.org:8123", auth: {:basic, "user:pass"})
iex> Req.post!(req, body: "SELECT number FROM system.numbers LIMIT 3").body
"0\n1\n2\n"

@spec query(
  Req.Request.t(),
  sql_query :: binary(),
  sql_query_params :: map() | Keyword.t(),
  opts :: Keyword.t()
) :: {:ok, Req.Response.t()} | {:error, binary()}

Performs a query against the ClickHouse API.

By default, it will use the http://localhost:8123 as :base_url. You can change that either providing in your Req request, or in passing down in the options.

query/4 accepts any option that new/1 accepts.

Examples

This function wraps Req.get/2 and Req.post/2 to automatically perform parameter encoding.

A plain query:

iex> req = ReqCH.new(database: "system")
iex> {:ok, response} = ReqCH.query(req, "SELECT number FROM numbers LIMIT 3")
iex> response.body
"0\n1\n2\n"

With the :adbc format:

iex> req = ReqCH.new(database: "system")
iex> {:ok, response} = ReqCH.query(req, "SELECT number FROM numbers LIMIT 3", [], [format: :adbc])
iex> response.body
%Adbc.Result{
   data: [
    [
      %Adbc.Column{
        field: %Adbc.Field{name: "number", type: :u64, metadata: nil},
        data: %Adbc.BufferData{
          data: <<0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0>>,
          validity: nil,
          bit_offset: 0
        },
        size: nil
      }
    ]
   ],
   num_rows: nil
 }

With the :explorer format:

iex> req = ReqCH.new(database: "system")
iex> {:ok, response} = ReqCH.query(req, "SELECT number FROM numbers LIMIT 3", [], [format: :explorer])
iex> response.body
#Explorer.DataFrame<
  Polars[3 x 1]
  number u64 [0, 1, 2]
>

Passing SQL params:

iex> req = ReqCH.new(database: "system")
iex> {:ok, response} = ReqCH.query(req, "SELECT number FROM numbers WHERE number > {num:UInt8} LIMIT 3", [num: 5], [])
iex> response.body
"6\n7\n8\n"

This function can accept Req options, as well as mixing them with ReqCH options:

iex> opts = [base_url: "http://example.org:8123", database: "system", auth: {:basic, "user:pass"}]
iex> {:ok, response} = ReqCH.query(ReqCH.new(), "SELECT number FROM numbers LIMIT 3", [], opts)
iex> response.body
"0\n1\n2\n"

@spec query!(
  Req.Request.t(),
  sql_query :: binary(),
  sql_query_params :: map() | Keyword.t(),
  opts :: Keyword.t()
) :: Req.Response.t()

Same as query/4, but raises in case of error.