WeaviateEx.API.Aggregate (WeaviateEx v0.7.4)

@type metric() ::
  :count
  | :sum
  | :mean
  | :median
  | :mode
  | :maximum
  | :minimum
  | :topOccurrences
  | :percentageTrue
  | :percentageFalse
  | :totalTrue
  | :totalFalse

opts()

@type opts() :: keyword()

Functions

group_by(client, collection_name, property, opts \\ [])

@spec group_by(WeaviateEx.Client.t(), collection_name(), String.t(), opts()) ::
  {:ok, [map()]} | {:error, WeaviateEx.Error.t()}

Aggregate results grouped by property.

Parameters

client - WeaviateEx client
collection_name - Name of the collection
property - Property to group by (supports nested paths like "author.name")
opts - Options (same as over_all/3)

Examples

{:ok, results} = Aggregate.group_by(client, "Article", "category",
  metrics: [:count]
)

{:ok, results} = Aggregate.group_by(client, "Article", "author",
  properties: [
    {:views, [:mean, :sum]}
  ],
  metrics: [:count]
)

Returns

{:ok, [map()]} - List of grouped aggregation results
{:error, Error.t()} - Error if aggregation fails

over_all(client, collection_name, opts \\ [])

@spec over_all(WeaviateEx.Client.t(), collection_name(), opts()) ::
  {:ok, [map()]} | {:error, WeaviateEx.Error.t()}

Aggregate entire collection with specified metrics.

Parameters

client - WeaviateEx client
collection_name - Name of the collection
opts - Options:
- :metrics - List of meta metrics ([:count])
- :properties - List of {property, metrics} or {property, metrics, opts} tuples

Examples

# Count all objects
{:ok, results} = Aggregate.over_all(client, "Article", metrics: [:count])

# Aggregate numeric properties
{:ok, results} = Aggregate.over_all(client, "Product",
  properties: [
    {:price, [:sum, :mean, :maximum, :minimum]}
  ]
)

# Text property with top occurrences
{:ok, results} = Aggregate.over_all(client, "Article",
  properties: [
    {:category, [:topOccurrences], limit: 5}
  ]
)

Returns

{:ok, [map()]} - List of aggregation results
{:error, Error.t()} - Error if aggregation fails

with_hybrid(client, collection_name, query, opts \\ [])

@spec with_hybrid(WeaviateEx.Client.t(), collection_name(), String.t(), opts()) ::
  {:ok, [map()]} | {:error, WeaviateEx.Error.t()}

Aggregate with hybrid search constraint.

Combines vector similarity and keyword (BM25) search for aggregation.

Parameters

client - WeaviateEx client
collection_name - Name of the collection
query - Search query string
opts - Options including:
- :alpha - Weight between vector (1.0) and keyword (0.0) search (default: 0.5)
- :fusion_type - Fusion strategy (:ranked or :relative_score)
- Plus standard aggregation options

Examples

{:ok, results} = Aggregate.with_hybrid(client, "Article",
  "machine learning",
  alpha: 0.7,
  metrics: [:count]
)

{:ok, results} = Aggregate.with_hybrid(client, "Article",
  "popular topics",
  alpha: 0.5,
  fusion_type: :ranked,
  properties: [
    {:views, [:mean, :sum]}
  ]
)

Returns

{:ok, [map()]} - List of aggregation results
{:error, Error.t()} - Error if aggregation fails

with_near_image(client, collection_name, image_data, opts \\ [])

@spec with_near_image(WeaviateEx.Client.t(), collection_name(), String.t(), opts()) ::
  {:ok, [map()]} | {:error, WeaviateEx.Error.t()}

Aggregate with near_image similarity constraint.

Aggregates objects that are semantically similar to a given image. The image can be provided as a base64-encoded string or a URL.

Requires a multi2vec-clip or similar image-capable vectorizer.

Parameters

client - WeaviateEx client
collection_name - Name of the collection
image_data - Base64-encoded image string or image URL
opts - Options including:
- :certainty - Minimum certainty threshold
- :distance - Maximum distance threshold
- :target_vectors - Target named vectors for multi-vector collections
- Plus standard aggregation options

Examples

# With base64 image
{:ok, results} = Aggregate.with_near_image(client, "Products",
  base64_image_string,
  metrics: [:count]
)

# With certainty threshold
{:ok, results} = Aggregate.with_near_image(client, "Products",
  image_data,
  certainty: 0.7,
  metrics: [:count]
)

# Target specific named vector
{:ok, results} = Aggregate.with_near_image(client, "Products",
  image_data,
  target_vectors: ["image_vector"],
  properties: [{:price, [:mean, :sum]}]
)

Returns

{:ok, [map()]} - List of aggregation results
{:error, Error.t()} - Error if aggregation fails

with_near_object(client, collection_name, object_id, opts \\ [])

@spec with_near_object(WeaviateEx.Client.t(), collection_name(), String.t(), opts()) ::
  {:ok, [map()]} | {:error, WeaviateEx.Error.t()}

Aggregate with near_object similarity constraint.

Aggregates objects that are semantically similar to a given object.

Parameters

client - WeaviateEx client
collection_name - Name of the collection
object_id - UUID of the reference object
opts - Options (same as over_all/3 plus :certainty, :distance)

Examples

{:ok, results} = Aggregate.with_near_object(client, "Article",
  "550e8400-e29b-41d4-a716-446655440000",
  metrics: [:count],
  distance: 0.3
)

Returns

{:ok, [map()]} - List of aggregation results
{:error, Error.t()} - Error if aggregation fails

with_near_text(client, collection_name, concepts, opts \\ [])

@spec with_near_text(WeaviateEx.Client.t(), collection_name(), String.t(), opts()) ::
  {:ok, [map()]} | {:error, WeaviateEx.Error.t()}

Aggregate with semantic text search context.

Parameters

client - WeaviateEx client
collection_name - Name of the collection
concepts - Search concepts/query
opts - Options (same as over_all/3 plus :certainty, :distance)

Examples

{:ok, results} = Aggregate.with_near_text(client, "Article",
  "artificial intelligence",
  metrics: [:count]
)

{:ok, results} = Aggregate.with_near_text(client, "Article",
  "popular topics",
  certainty: 0.7,
  properties: [
    {:views, [:mean, :sum]}
  ]
)

Returns

{:ok, [map()]} - List of aggregation results
{:error, Error.t()} - Error if aggregation fails

with_near_vector(client, collection_name, vector, opts \\ [])

@spec with_near_vector(WeaviateEx.Client.t(), collection_name(), [float()], opts()) ::
  {:ok, [map()]} | {:error, WeaviateEx.Error.t()}

Aggregate with vector similarity search.

Parameters

client - WeaviateEx client
collection_name - Name of the collection
vector - Search vector
opts - Options (same as over_all/3 plus :certainty, :distance)

Examples

{:ok, results} = Aggregate.with_near_vector(client, "Article", vector,
  metrics: [:count]
)

Returns

{:ok, [map()]} - List of aggregation results
{:error, Error.t()} - Error if aggregation fails

with_where(client, collection_name, filter, opts \\ [])

@spec with_where(WeaviateEx.Client.t(), collection_name(), map(), opts()) ::
  {:ok, [map()]} | {:error, WeaviateEx.Error.t()}

Aggregate with filter conditions.

Parameters

client - WeaviateEx client
collection_name - Name of the collection
filter - Filter map (GraphQL where clause format)
opts - Options (same as over_all/3)

Examples

filter = %{
  path: ["status"],
  operator: "Equal",
  valueText: "published"
}

{:ok, results} = Aggregate.with_where(client, "Article", filter,
  metrics: [:count]
)

Returns

{:ok, [map()]} - List of aggregation results
{:error, Error.t()} - Error if aggregation fails