Greptimex.Connection behaviour (Greptimex v0.2.6)

View Source

Defines a GreptimeDB connection module.

When used, it sets up a connection pool and provides functions for inserting data and querying with PromQL.

Configuration

Required

Optional

  • :header - Default header options passed with each request
    • :catalog - The catalog name. Default: "greptime"
    • :dbname - The database name. Default: "public"
    • :schema - The schema name. Default: nil
    • :timezone - The timezone for timestamp interpretation. Default: nil
    • :auth - Authentication credentials as {:basic, {username, password}} tuple. Default: nil
  • :defaults - Default options for insert operations
    • :timestamp_name - The column name for timestamps. Default: "greptime_timestamp"
    • :timestamp_datatype - The datatype for timestamps. Default: :TIMESTAMP_MILLISECOND
  • :otp_app - The OTP application to fetch configuration from. If provided, the module will read its configuration from the application's environment using the module name as the key.

Example

defmodule MyApp.Greptimex do
  use Greptimex.Connection,
    pool: [
      pool_size: 5,
      channel: [address: "localhost:50051", opts: []]
    ],
    header: [
      catalog: "greptime",
      dbname: "public",
      auth: {:basic, {"username", "password"}}
    ]
end

Summary

Types

t()

Callbacks

insert(rows, opts)

Inserts rows into GreptimeDB. Supports single/multiple rows and single/multiple tables.

query_instant(query, time, lookback, opts)

Executes a PromQL instant query at a specific time.

query_range(query, start_time, end_time, step, lookback, opts)

Executes a PromQL range query over a time period.

Functions

header(opts)

Types

t()

@type t() :: module()

Callbacks

insert(rows, opts)

@callback insert(rows :: term(), opts :: Keyword.t()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Inserts rows into GreptimeDB. Supports single/multiple rows and single/multiple tables.

Examples

# Single row, single table
MyApp.Greptimex.insert({"metrics", %{tags: %{host: "server1"}, fields: %{cpu: 0.8}, timestamp: ~U[2025-01-01 00:00:00Z]}})
{:ok, 1}

# Multiple rows, single table
MyApp.Greptimex.insert({"metrics", [
  %{tags: %{host: "server1"}, fields: %{cpu: 0.8}, timestamp: ~U[2025-01-01 00:00:00Z]},
  %{tags: %{host: "server2"}, fields: %{cpu: 0.5}, timestamp: ~U[2025-01-01 00:00:01Z]}
]})
{:ok, 2}

# Multiple rows, multiple tables
MyApp.Greptimex.insert([
  {"metrics", [
    %{tags: %{host: "server1"}, fields: %{cpu: 0.8}, timestamp: ~U[2025-01-01 00:00:00Z]},
    %{tags: %{host: "server2"}, fields: %{cpu: 0.5}, timestamp: ~U[2025-01-01 00:00:01Z]}
  ]},
  {"logs", [
    %{tags: %{level: "info"}, fields: %{message: "test"}, timestamp: ~U[2025-01-01 00:00:00Z]},
    %{tags: %{level: "error"}, fields: %{message: "failed"}, timestamp: ~U[2025-01-01 00:00:01Z]}
  ]}
])
{:ok, 4}

query_instant(query, time, lookback, opts)

@callback query_instant(
  query :: String.t(),
  time :: DateTime.t() | integer(),
  lookback :: String.t(),
  opts :: Keyword.t()
) :: {:ok, list()} | {:error, term()}

Executes a PromQL instant query at a specific time.

Examples

MyApp.Greptimex.query_instant("up")
{:ok, [%{metric: %{"__name__" => "up"}, value: {~U[2025-01-01 12:00:00Z], 1.0}}]}

MyApp.Greptimex.query_instant("up{job='api'}", ~U[2025-01-01 12:00:00Z])
{:ok, [%{metric: %{"__name__" => "up", "job" => "api"}, value: {~U[2025-01-01 12:00:00Z], 1.0}}]}

query_range(query, start_time, end_time, step, lookback, opts)

@callback query_range(
  query :: String.t(),
  start_time :: DateTime.t() | integer(),
  end_time :: DateTime.t() | integer(),
  step :: String.t(),
  lookback :: String.t(),
  opts :: Keyword.t()
) :: {:ok, list()} | {:error, term()}

Executes a PromQL range query over a time period.

Examples

MyApp.Greptimex.query_range("up", ~U[2025-01-01 00:00:00Z], ~U[2025-01-01 01:00:00Z], "5m")
{:ok, [%{metric: %{"__name__" => "up"}, values: [...]}]}

Functions

header(opts)