@spec additional(t(), [String.t()]) :: t()

Adds additional fields to retrieve (like id, certainty, distance).

Examples

query
|> WeaviateEx.Query.additional(["id", "certainty", "distance"])

@spec after_cursor(t(), String.t()) :: t()

Sets the cursor for cursor-based pagination.

Cursor pagination is more memory-efficient than offset-based pagination for large result sets. Use the cursor value from the last object's _additional.id to fetch the next page.

Note: Cursor pagination requires consistent sorting. Use with sort/2 for deterministic results, typically sorting by ID.

Examples

# First page
query
|> WeaviateEx.Query.limit(100)
|> WeaviateEx.Query.sort(Sort.by_id())

# Subsequent pages using the last ID as cursor
query
|> WeaviateEx.Query.limit(100)
|> WeaviateEx.Query.sort(Sort.by_id())
|> WeaviateEx.Query.after_cursor("last-object-id")

@spec auto_limit(t(), pos_integer()) :: t()

Sets the auto-limit for automatically cutting off results at natural score boundaries.

Auto-limit is useful with vector searches where you want to stop returning results when there's a natural gap in similarity scores. The value represents the number of "jumps" or score discontinuities to allow before cutting off.

Examples

# Cut off after 3 natural score boundaries
query
|> WeaviateEx.Query.auto_limit(3)

# Combined with near_text for semantic search with auto-cutoff
query
|> WeaviateEx.Query.near_text("machine learning")
|> WeaviateEx.Query.auto_limit(2)

@spec bm25(t(), String.t(), Keyword.t()) :: t()

Performs BM25 keyword search.

Examples

query
|> WeaviateEx.Query.bm25("machine learning")

@spec execute(t()) :: WeaviateEx.api_response()

Executes the query and returns results.

When called with a WeaviateEx.Client, uses gRPC for optimal performance. When called without a client (legacy mode), uses HTTP/GraphQL.

Examples

# With client (uses gRPC)
{:ok, client} = WeaviateEx.Client.connect(base_url: "http://localhost:8080")
{:ok, results} = Query.execute(query, client)

# Legacy mode (uses HTTP/GraphQL)
{:ok, results} = Query.execute(query)

@spec fields(t(), [String.t()]) :: t()

Specifies which fields to retrieve.

Examples

query
|> WeaviateEx.Query.fields(["title", "content", "publishedAt"])

@spec generate(t(), :single | :grouped, String.t(), keyword()) ::
  WeaviateEx.Query.Generate.t()

Adds generative AI capabilities to a query.

Combines the existing query with generative configuration to produce AI-generated content alongside search results.

Parameters

• query - The existing query struct
• type - Generation type (:single for per-object, :grouped for all results)
• prompt - The prompt to use for generation
• opts - Additional options

Options

• :properties - Properties to include in grouped context (for :grouped type)

Examples

# Add per-object generation to existing query
query
|> Query.near_text("machine learning")
|> Query.generate(:single, "Summarize: {title}")
|> Query.execute(client)

# Add grouped generation with specific properties
query
|> Query.bm25("elixir")
|> Query.generate(:grouped, "Write an overview", properties: ["title", "content"])
|> Query.execute(client)

Returns

A Generate struct that can be executed to get GenerativeResult.

@spec get(String.t()) :: t()

Starts a Get query for a collection.

Examples

query = WeaviateEx.Query.get("Article")

@spec group_by(t(), WeaviateEx.Query.GroupBy.t()) :: t()

Groups query results by a property.

GroupBy clusters results based on a property path, returning groups with their objects. This is useful for organizing search results by category, type, or other grouping criteria.

Parameters

• query - The query struct
• group_by - A WeaviateEx.Query.GroupBy struct

Examples

alias WeaviateEx.Query.GroupBy

# Group by category
group_by = GroupBy.new("category")
query
|> WeaviateEx.Query.group_by(group_by)

# Group with custom limits
group_by = GroupBy.new("category", objects_per_group: 5, number_of_groups: 20)
query
|> WeaviateEx.Query.near_text("technology")
|> WeaviateEx.Query.group_by(group_by)

# Group by nested property
group_by = GroupBy.new(["metadata", "type"])
query
|> WeaviateEx.Query.group_by(group_by)

@spec hybrid(t(), String.t(), Keyword.t()) :: t()

Performs hybrid search combining keyword and vector search.

Options

• :alpha - Balance between keyword (0.0) and vector (1.0) search, default: 0.5
• :vector - HybridVector configuration for advanced vector search
• :fusion_type - Fusion algorithm: :ranked or :relative_score
• :properties - Properties to search for BM25 component
• :target_vectors - Target vectors for multi-vector collections
• :max_vector_distance - Maximum distance for vector similarity in hybrid search
• :bm25_operator - BM25Operator configuration for keyword matching (AND/OR)

Examples

# Basic hybrid search
query
|> WeaviateEx.Query.hybrid("machine learning", alpha: 0.75)

# With HybridVector for advanced vector search
hv = HybridVector.near_text("concepts",
  move_to: Move.to(0.5, concepts: ["AI"])
)
query
|> WeaviateEx.Query.hybrid("search term", vector: hv, alpha: 0.7)

# With explicit vector
hv = HybridVector.near_vector(embedding)
query
|> WeaviateEx.Query.hybrid("search", vector: hv, fusion_type: :relative_score)

# With max_vector_distance
query
|> WeaviateEx.Query.hybrid("search", max_vector_distance: 0.5)

# With BM25 operator
query
|> WeaviateEx.Query.hybrid("machine learning", bm25_operator: BM25Operator.and_())

@spec limit(t(), integer()) :: t()

Sets the maximum number of results.

Examples

query |> WeaviateEx.Query.limit(10)

@spec near_image(
  t(),
  keyword()
) :: t()

Performs image-based vector search for multimodal collections.

Supports multi2vec-clip, multi2vec-bind, and other image vectorizers.

Options

• :image - Base64-encoded image data
• :image_file - Path to image file (will be read and base64 encoded)
• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :target_vectors - List of named vectors to target

Either :image or :image_file must be provided, but not both.

Examples

# Search by base64 encoded image
query
|> WeaviateEx.Query.near_image(image: base64_data, certainty: 0.8)

# Search by file path
query
|> WeaviateEx.Query.near_image(image_file: "/path/to/image.png")

# With named vectors
query
|> WeaviateEx.Query.near_image(image: data, target_vectors: ["image_vector"])

@spec near_media(t(), WeaviateEx.Query.NearMedia.media_type(), keyword()) :: t()

Performs media-based vector search for multimodal collections.

Supports audio, video, thermal, depth, and IMU data types for multi2vec-bind and similar multimodal vectorizers.

Media Types

• :audio - Audio files (wav, mp3, etc.)
• :video - Video files (mp4, avi, etc.)
• :thermal - Thermal imaging data
• :depth - Depth sensor data
• :imu - Inertial measurement unit data

Options

• :media - Base64-encoded media data
• :media_file - Path to media file (will be read and base64 encoded)
• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :target_vectors - List of named vectors to target

Either :media or :media_file must be provided, but not both.

Examples

# Search by audio
query
|> WeaviateEx.Query.near_media(:audio, media: base64_audio, certainty: 0.7)

# Search by video file
query
|> WeaviateEx.Query.near_media(:video, media_file: "/path/to/video.mp4")

# With named vectors
query
|> WeaviateEx.Query.near_media(:thermal, media: data, target_vectors: ["thermal_vec"])

@spec near_object(t(), String.t(), Keyword.t()) :: t()

Finds objects similar to a specific object.

Options

• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :target_vectors - Target vectors for multi-vector collections

Examples

query
|> WeaviateEx.Query.near_object("550e8400-e29b-41d4-a716-446655440000", certainty: 0.7)

# With target vectors
query
|> WeaviateEx.Query.near_object("550e8400-e29b-41d4-a716-446655440000",
  target_vectors: "title_vector"
)

@spec near_text(t(), String.t(), Keyword.t()) :: t()

Performs semantic search using natural language.

Options

• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :move_to - Move struct to shift results towards concepts/objects
• :move_away - Move struct to shift results away from concepts/objects
• :target_vectors - Target vectors for multi-vector collections

Examples

# Simple near_text query
query
|> WeaviateEx.Query.near_text("artificial intelligence", certainty: 0.7)

# With move_to to shift towards concepts
alias WeaviateEx.Query.Move
move_to = Move.to(0.5, concepts: ["summer", "beach"])
query
|> WeaviateEx.Query.near_text("vacation", move_to: move_to)

# With move_away to shift away from concepts
move_away = Move.to(0.3, concepts: ["winter", "cold"])
query
|> WeaviateEx.Query.near_text("vacation", move_away: move_away)

# With both move_to and move_away
query
|> WeaviateEx.Query.near_text("vacation",
  certainty: 0.7,
  move_to: Move.to(0.5, concepts: ["summer"]),
  move_away: Move.to(0.25, concepts: ["winter"])
)

# With target vectors for multi-vector collections
query
|> WeaviateEx.Query.near_text("machine learning", target_vectors: "content_vector")

@spec near_vector(t(), [float()], Keyword.t()) :: t()

Performs vector similarity search.

Options

• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :target_vectors - Target vectors for multi-vector collections

Examples

# Single vector collection
query
|> WeaviateEx.Query.near_vector([0.1, 0.2, 0.3, ...], certainty: 0.8)

# Multi-vector collection with single target
query
|> WeaviateEx.Query.near_vector([0.1, 0.2, 0.3],
  target_vectors: "title_vector",
  distance: 0.2
)

# Combined target vectors
target = TargetVectors.combine(["vec1", "vec2"], method: :average)
query
|> WeaviateEx.Query.near_vector(vector, target_vectors: target)

@spec offset(t(), integer()) :: t()

Sets the offset for pagination.

Examples

query |> WeaviateEx.Query.offset(20)

@spec rerank(t(), WeaviateEx.Query.Rerank.t()) :: t()

Adds reranking to the query results.

Reranking uses a reranker model configured on the collection to re-order search results based on relevance to the query. The reranker scores are available in the _additional { rerank { score } } field.

Parameters

• query - The query struct
• rerank - A WeaviateEx.Query.Rerank struct

Examples

alias WeaviateEx.Query.Rerank

# Basic rerank
rerank = Rerank.new("content")
query
|> WeaviateEx.Query.rerank(rerank)

# Rerank with custom query
rerank = Rerank.new("content", query: "What is machine learning?")
query
|> WeaviateEx.Query.near_text("AI")
|> WeaviateEx.Query.rerank(rerank)

@spec return_references(t(), [WeaviateEx.Query.QueryReference.t()]) :: t()

Sets the cross-references to fetch with the query results.

Allows fetching related objects through cross-reference properties. Use WeaviateEx.Query.QueryReference to build reference configurations with property selection and nested reference support.

Examples

# Simple reference
ref = QueryReference.new("hasAuthor", return_properties: ["name"])
query
|> WeaviateEx.Query.return_references([ref])

# Reference with nested references
nested = QueryReference.new("hasPublisher", return_properties: ["name"])
ref = QueryReference.new("hasAuthor",
  return_properties: ["name", "bio"],
  return_references: [nested]
)
query
|> WeaviateEx.Query.return_references([ref])

# Multiple references
author_ref = QueryReference.new("hasAuthor", return_properties: ["name"])
category_ref = QueryReference.new("hasCategory", return_properties: ["name"])
query
|> WeaviateEx.Query.return_references([author_ref, category_ref])

@spec sort(t(), WeaviateEx.Query.Sort.t()) :: t()

Sets the sort criteria for the query.

Accepts sort criteria built using the WeaviateEx.Query.Sort module. Sort can be used for ordering results and is required for deterministic cursor-based pagination.

Examples

# Sort by a single property
query
|> WeaviateEx.Query.sort(Sort.by_property("title", :asc))

# Sort by ID (useful for cursor pagination)
query
|> WeaviateEx.Query.sort(Sort.by_id())

# Sort by creation time descending (newest first)
query
|> WeaviateEx.Query.sort(Sort.by_creation_time(:desc))

# Sort by update time
query
|> WeaviateEx.Query.sort(Sort.by_update_time(:desc))

# Multiple sort criteria
query
|> WeaviateEx.Query.sort(
  Sort.by_property("category")
  |> Sort.then_by_property("title", :desc)
)

@spec tenant(t(), String.t()) :: t()

Sets the tenant for multi-tenant collections.

Examples

query
|> WeaviateEx.Query.tenant("TenantA")

@spec where(t(), map()) :: t()

Adds a where filter clause.

Examples

query
|> WeaviateEx.Query.where(%{
  path: ["title"],
  operator: "Equal",
  valueText: "Hello World"
})

@spec with_near_audio(t(), String.t() | binary(), keyword()) :: t()

Searches by audio similarity.

Accepts file paths, base64-encoded data, or raw binary data.

Arguments

• query - The query struct
• audio - Audio data as file path, base64 string, or raw binary
• opts - Optional keyword options

Options

• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :target_vectors - Target vectors for multi-vector collections

Examples

Query.get("Podcasts")
|> Query.with_near_audio("/path/to/clip.mp3")
|> Query.limit(10)
|> Query.execute(client)

Note: Requires a multi-modal vectorizer that supports audio (e.g., multi2vec-bind).

@spec with_near_depth(t(), String.t() | binary(), keyword()) :: t()

Searches by depth map similarity.

Accepts file paths, base64-encoded data, or raw binary data.

Arguments

• query - The query struct
• depth - Depth map data as file path, base64 string, or raw binary
• opts - Optional keyword options

Options

• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :target_vectors - Target vectors for multi-vector collections

Examples

Query.get("DepthMaps")
|> Query.with_near_depth("/path/to/depth_map.png")
|> Query.execute(client)

Note: Requires a multi-modal vectorizer that supports depth data.

@spec with_near_image(t(), String.t() | binary(), keyword()) :: t()

Searches by image similarity.

Accepts file paths, base64-encoded data, or raw binary data. Automatically detects the input type and handles encoding.

Arguments

• query - The query struct
• image - Image data as file path, base64 string, or raw binary
• opts - Optional keyword options

Options

• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :target_vectors - Target vectors for multi-vector collections

Examples

# Search by image file path
Query.get("Products")
|> Query.with_near_image("/path/to/image.jpg")
|> Query.limit(10)
|> Query.execute(client)

# Search by base64 image
Query.get("Products")
|> Query.with_near_image(base64_image_data)
|> Query.execute(client)

# With options
Query.get("Products")
|> Query.with_near_image(image, certainty: 0.8, target_vectors: ["image_vector"])
|> Query.execute(client)

Note: Requires a multi-modal vectorizer (e.g., multi2vec-clip).

@spec with_near_imu(t(), String.t() | binary(), keyword()) :: t()

Searches by IMU (Inertial Measurement Unit) data similarity.

Accepts file paths, base64-encoded data, or raw binary data.

Arguments

• query - The query struct
• imu - IMU data as file path, base64 string, or raw binary
• opts - Optional keyword options

Options

• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :target_vectors - Target vectors for multi-vector collections

Examples

Query.get("SensorData")
|> Query.with_near_imu(imu_data)
|> Query.execute(client)

Note: Requires a multi-modal vectorizer that supports IMU data.

@spec with_near_media(
  t(),
  WeaviateEx.Types.MediaType.t(),
  String.t() | binary(),
  keyword()
) :: t()

Generic multi-modal search with automatic input handling.

Accepts file paths, base64-encoded data, or raw binary data for any supported media type.

Arguments

• query - The query struct
• media_type - The media type (:image, :audio, :video, :thermal, :depth, :imu)
• media - Media data as file path, base64 string, or raw binary
• opts - Optional keyword options

Options

• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :target_vectors - Target vectors for multi-vector collections

Examples

# Image search
Query.get("Products")
|> Query.with_near_media(:image, "/path/to/image.jpg")
|> Query.execute(client)

# Audio search with options
Query.get("Podcasts")
|> Query.with_near_media(:audio, audio_data, certainty: 0.8)
|> Query.execute(client)

@spec with_near_thermal(t(), String.t() | binary(), keyword()) :: t()

Searches by thermal image similarity.

Accepts file paths, base64-encoded data, or raw binary data.

Arguments

• query - The query struct
• thermal - Thermal image data as file path, base64 string, or raw binary
• opts - Optional keyword options

Options

• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :target_vectors - Target vectors for multi-vector collections

Examples

Query.get("ThermalImages")
|> Query.with_near_thermal("/path/to/thermal.png")
|> Query.execute(client)

Note: Requires a multi-modal vectorizer that supports thermal data.

@spec with_near_video(t(), String.t() | binary(), keyword()) :: t()

Searches by video similarity.

Accepts file paths, base64-encoded data, or raw binary data.

Arguments

• query - The query struct
• video - Video data as file path, base64 string, or raw binary
• opts - Optional keyword options

Options

• :certainty - Minimum certainty threshold (0.0 to 1.0)
• :distance - Maximum distance threshold
• :target_vectors - Target vectors for multi-vector collections

Examples

Query.get("Videos")
|> Query.with_near_video("/path/to/clip.mp4")
|> Query.limit(10)
|> Query.execute(client)

Note: Requires a multi-modal vectorizer that supports video (e.g., multi2vec-bind).

@spec with_tenant(t(), String.t()) :: t()

Scopes the query to a specific tenant (alias for tenant/2).

This provides a more fluent API matching the Python client's with_tenant pattern. Functionally identical to tenant/2.

Examples

query
|> WeaviateEx.Query.with_tenant("TenantA")