Trifle.Stats
v2.5.0

View Source Trifle.Stats.Nocturnal.Key (Trifle.Stats v2.5.0)

Key structure for trifle-stats operations.

Represents a structured key used in time-series data storage operations. Keys contain the base key name, time granularity, timestamp, and optional prefix.

Usage 

# Create a key with base components
key = Trifle.Stats.Nocturnal.Key.new(key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z])

# Set a prefix (usually done by drivers)
key = Trifle.Stats.Nocturnal.Key.set_prefix(key, "stats")

# Join components into a storage key
joined = Trifle.Stats.Nocturnal.Key.join(key, "::")
# => "stats::page_views::hour::1692266400"

# Get identifier for storage (joined or separated)
identifier = Trifle.Stats.Nocturnal.Key.identifier(key, "::")
# => %{key: "stats::page_views::hour::1692266400"}

identifier = Trifle.Stats.Nocturnal.Key.identifier(key, "::", nil)
# => %{key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z]}

Fields

  • :key - The base key name (string)
  • :granularity - Time granularity (string or atom: "minute", "hour", "day", "week", "month", "quarter", "year")
  • :at - Timestamp (DateTime or integer unix timestamp)
  • :prefix - Optional prefix string set by drivers for namespacing

Summary

Types

t()

Functions

identifier(key, separator, mode \\ :full)

Returns an identifier suitable for driver storage.

join(key, separator)

Joins all key components into a single string using the provided separator.

new(opts \\ [])

Creates a new Key struct.

set_prefix(key, prefix)

Sets a prefix on the key.

simple_identifier(key, separator, mode \\ :full)

Returns a simplified identifier for consistent map key lookup.

Types

Link to this type

t()

View Source 
@type t() :: %Trifle.Stats.Nocturnal.Key{
  at: DateTime.t() | integer() | nil,
  granularity: String.t() | atom() | nil,
  key: String.t(),
  prefix: String.t() | nil
}

Functions

Link to this function

identifier(key, separator, mode \\ :full)

View Source 
@spec identifier(t(), String.t() | nil, atom() | String.t() | nil) :: map()

Returns an identifier suitable for driver storage.

If mode is nil, returns a map with separate key components. If mode is :full or "full", joins all components. If mode is :partial or "partial", joins only key and granularity and keeps at separate.

Examples 

# Joined mode (for drivers that store keys as single strings)
iex> key = Trifle.Stats.Nocturnal.Key.new(key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z])
iex> Trifle.Stats.Nocturnal.Key.identifier(key, "::")
%{key: "page_views::hour::1692266400"}

# Partial-joined mode (for drivers that store timestamps separately)
iex> key = Trifle.Stats.Nocturnal.Key.new(key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z])
iex> Trifle.Stats.Nocturnal.Key.identifier(key, "::", :partial)
%{key: "page_views::hour", at: ~U[2025-08-17 10:00:00Z]}

# Separated mode (for drivers that store key components separately)
iex> key = Trifle.Stats.Nocturnal.Key.new(key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z])
iex> Trifle.Stats.Nocturnal.Key.identifier(key, "::", nil)
%{key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z]}
Link to this function

join(key, separator)

View Source 
@spec join(t(), String.t()) :: String.t()

Joins all key components into a single string using the provided separator.

Combines prefix, key, granularity, and timestamp (as unix integer) into a single storage key. Only includes non-nil components.

Examples 

iex> key = Trifle.Stats.Nocturnal.Key.new(key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z])
iex> key = Trifle.Stats.Nocturnal.Key.set_prefix(key, "stats") 
iex> Trifle.Stats.Nocturnal.Key.join(key, "::")
"stats::page_views::hour::1692266400"
Link to this function

new(opts \\ [])

View Source 
@spec new(
  key: String.t(),
  granularity: String.t() | atom() | nil,
  at: DateTime.t() | integer() | nil
) ::
  t()

Creates a new Key struct.

Parameters

  • key - The base key name (required)
  • granularity - Time granularity identifier (optional)
  • at - Timestamp for the time bucket (optional)

Examples 

iex> Trifle.Stats.Nocturnal.Key.new(key: "metrics")
%Trifle.Stats.Nocturnal.Key{key: "metrics", granularity: nil, at: nil, prefix: nil}

iex> Trifle.Stats.Nocturnal.Key.new(key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z])
%Trifle.Stats.Nocturnal.Key{key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z], prefix: nil}
Link to this function

set_prefix(key, prefix)

View Source 
@spec set_prefix(t(), String.t()) :: t()

Sets a prefix on the key.

Typically called by drivers to add their own namespace prefix.

Examples 

iex> key = Trifle.Stats.Nocturnal.Key.new(key: "metrics")
iex> Trifle.Stats.Nocturnal.Key.set_prefix(key, "stats")
%Trifle.Stats.Nocturnal.Key{key: "metrics", granularity: nil, at: nil, prefix: "stats"}
Link to this function

simple_identifier(key, separator, mode \\ :full)

View Source 
@spec simple_identifier(t(), String.t() | nil, atom() | String.t() | nil) :: map()

Returns a simplified identifier for consistent map key lookup.

Always converts timestamps to unix integers for consistent mapping, regardless of the original timestamp format. Used internally by drivers for result mapping and lookup operations.

If mode is nil, returns a map with separate key components. If mode is :full or "full", joins all components. If mode is :partial or "partial", joins only key and granularity and keeps at separate.

Examples 

# Joined mode
iex> key = Trifle.Stats.Nocturnal.Key.new(key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z])
iex> Trifle.Stats.Nocturnal.Key.simple_identifier(key, "::")
%{key: "page_views::hour::1692266400"}

# Partial-joined mode
iex> key = Trifle.Stats.Nocturnal.Key.new(key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z])
iex> Trifle.Stats.Nocturnal.Key.simple_identifier(key, "::", :partial)
%{key: "page_views::hour", at: 1692266400}

# Separated mode
iex> key = Trifle.Stats.Nocturnal.Key.new(key: "page_views", granularity: "hour", at: ~U[2025-08-17 10:00:00Z])
iex> Trifle.Stats.Nocturnal.Key.simple_identifier(key, "::", nil)
%{key: "page_views", granularity: "hour", at: 1692266400}