Implementation:Mlflow Mlflow Search Prompts

Knowledge Sources	MLflow MLflow Prompt API
Domains	ML_Ops, Prompt_Engineering
Last Updated	2026-02-13 20:00 GMT

Overview

Concrete tool for searching and discovering prompt templates in the MLflow Prompt Registry using filter expressions, provided by the MLflow library.

Description

The mlflow.genai.search_prompts() function queries the MLflow Prompt Registry and returns a list of Prompt entities matching the specified criteria. It searches only for entries that have been marked as prompts (tagged with mlflow.prompt.is_prompt=true) and supports additional filtering via a SQL-like filter expression.

The function returns prompt-level metadata -- name, description, tags, and creation timestamp -- rather than version-specific content such as templates. To retrieve the actual template of a specific version, use mlflow.genai.load_prompt() on the desired prompt name and version.

Internally, the function delegates to mlflow.tracking._model_registry.fluent.search_prompts(), which handles pagination transparently by calling MlflowClient().search_prompts() in a loop and aggregating results into a PagedList. For Unity Catalog registries, the filter string must include catalog and schema qualifiers.

Usage

Use search_prompts() to discover what prompts are available in the registry before loading specific versions. This is useful for building prompt catalogs, auditing existing assets, or checking for duplicates before registering a new prompt.

Code Reference

Source Location

• Repository: mlflow
• File: mlflow/genai/prompts/__init__.py
• Lines: L146-152
• Delegates to: mlflow/tracking/_model_registry/fluent.py L671-731

Signature

def search_prompts(
    filter_string: str | None = None,
    max_results: int | None = None,
) -> PagedList[Prompt]:
    ...

Import

import mlflow.genai

# Then call:
# prompts = mlflow.genai.search_prompts(...)

I/O Contract

Inputs

Name	Type	Required	Description
filter_string	None	No	A SQL-like filter expression to restrict results (e.g., "name LIKE 'greeting%'"). For Unity Catalog registries, must include catalog and schema: "catalog = 'my_catalog' AND schema = 'my_schema'". Defaults to None (no filter).
max_results	None	No	The maximum number of prompts to return. Defaults to None (returns all matching prompts, paginated internally).

Outputs

Name	Type	Description
return value	PagedList[Prompt]	A list of Prompt entities. Each Prompt contains prompt-level metadata (not version-specific template content).

Prompt Entity Fields

Property	Type	Description
name	str	The name of the prompt.
description	None	The description of the prompt.
tags	dict[str, str]	Prompt-level metadata as key-value pairs.
creation_timestamp	None	Timestamp when the prompt was created (milliseconds since Unix epoch).

Usage Examples

Search All Prompts

import mlflow.genai

# List all registered prompts
prompts = mlflow.genai.search_prompts()

for prompt in prompts:
    print(f"Name: {prompt.name}, Description: {prompt.description}")

Search with Filter

import mlflow.genai

# Find prompts whose names start with "greeting"
prompts = mlflow.genai.search_prompts(filter_string="name LIKE 'greeting%'")

for prompt in prompts:
    print(f"Found: {prompt.name}")

Search and Load Versions

import mlflow.genai

# Discover prompts, then load specific versions
prompts = mlflow.genai.search_prompts(filter_string="name LIKE 'qa_%'")

for prompt in prompts:
    # Load the latest version of each matching prompt
    prompt_version = mlflow.genai.load_prompt(f"prompts:/{prompt.name}@latest")
    print(f"{prompt.name} v{prompt_version.version}: {prompt_version.template}")

Limit Results

import mlflow.genai

# Return at most 10 prompts
prompts = mlflow.genai.search_prompts(max_results=10)

print(f"Found {len(prompts)} prompts")

Unity Catalog Search

import mlflow.genai

# For Unity Catalog registries, include catalog and schema in the filter
prompts = mlflow.genai.search_prompts(
    filter_string="catalog = 'ml_catalog' AND schema = 'prompts'"
)

Related Pages

Implements Principle

• Principle:Mlflow_Mlflow_Prompt_Search_and_Versioning