Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Use the ai schema for new AI inference SQL in Azure HorizonDB. The current documentation targets azure_ai 2.5.6 or later, which includes the complete direct-inference API and *_step pipeline-builder names used in these articles. The extension is still named azure_ai; you don't install a separate extension named ai.
The legacy azure_ai.* inference functions and azure_openai.create_embeddings() remain available in 2.5.6 for compatibility. You don't need to rewrite every existing call before upgrading. This guide doesn't announce their deprecation or a removal date. For existing applications that aren't migrating yet, use the HorizonDB legacy AI functions reference.
Check your database version and function signatures
Run the following queries in each database that uses AI functions:
SELECT extversion
FROM pg_extension
WHERE extname = 'azure_ai';
SELECT version
FROM pg_available_extension_versions
WHERE name = 'azure_ai' AND version = '2.5.6';
Don't treat every 2.5.x build as interchangeable. Earlier builds can have different overloads, argument names, defaults, and pipeline-builder names. Inspect the installed functions before changing application SQL:
SELECT n.nspname AS schema_name,
p.proname AS function_name,
pg_get_function_arguments(p.oid) AS arguments,
pg_get_function_result(p.oid) AS result_type
FROM pg_proc AS p
JOIN pg_namespace AS n ON n.oid = p.pronamespace
WHERE (n.nspname IN ('ai', 'azure_ai')
AND p.proname IN (
'embed', 'generate', 'extract', 'rank', 'is_true',
'chunk', 'embed_step', 'generate_step', 'extract_step',
'rank_step', 'is_true_step', 'chunk_step'
))
OR (n.nspname = 'azure_openai' AND p.proname = 'create_embeddings')
ORDER BY schema_name, function_name, arguments;
If 2.5.6 isn't available on your server, continue using your installed API and the legacy reference until the service update is available. The extension update command doesn't download missing extension files.
Upgrade the extension
If your installed version is earlier than 2.5.6 and that version is available, an authorized administrator runs the following command on the primary (read-write) endpoint:
ALTER EXTENSION azure_ai UPDATE TO '2.5.6';
Recheck pg_extension after the update. Repeat the upgrade in each database that needs it. Don't downgrade a newer version or run individual ALTER FUNCTION statements instead of the bundled migrations.
Keep your existing registered model aliases. The schema migration doesn't require new model deployments. For setup, see AI Model Management or manual model registration.
Map legacy inference calls to the new API
These functions are synchronous inference functions, not pipeline builders:
| Operation | Legacy function | Preferred function | Migration detail |
|---|---|---|---|
| Embed text | azure_openai.create_embeddings() |
ai.embed() |
Pass text before model; rename input to text and max_attempts to retry_attempts. |
| Generate text or JSON | azure_ai.generate() |
ai.generate() |
Use named arguments. Supplying json_schema selects the JSONB-returning overload. |
| Extract entities | azure_ai.extract() |
ai.extract() |
Rename document to text; pass labels through data. The new positional order is text, model, data. |
| Evaluate a statement | azure_ai.is_true() |
ai.is_true() |
Use statement and optional model. |
| Rerank documents | azure_ai.rank() |
ai.rank() |
Rename document_contents to data and document_ids to ids. The new API places optional top_n before model. |
Use named arguments rather than changing only the schema name. Default model aliases must already be registered: default-embedding, default-chat, and default-reranker. Legacy overloads can use NULL model defaults; new inference overloads use the corresponding explicit default alias.
Migrate embedding calls
Before:
SELECT azure_openai.create_embeddings(
'my-embedding',
input => 'A session about building chatbots',
dimensions => 1536,
max_attempts => 3
)::vector(1536);
After:
SELECT ai.embed(
text => 'A session about building chatbots',
model => 'my-embedding',
dimensions => 1536,
retry_attempts => 3
)::vector(1536);
Both attempt parameters count the initial request. For ai.embed(), retry_attempts DEFAULT NULL uses three total attempts, and retry_delay_ms defaults to 1,000 milliseconds. The new function doesn't expose timeout_ms or throw_on_error; review callers that rely on custom timeouts or suppressed errors before migrating.
The scalar result is real[], not a pgvector value. Cast it to vector for storage and distance operators. Array input returns TABLE (embedding real[]). Use the same model and dimensions for documents and queries; don't regenerate existing embeddings solely because the function name changes.
For complete signatures and batch examples, see Generate vector embeddings.
Migrate extraction and generation
Before:
SELECT azure_ai.extract(
document => 'The headphones sound great.',
data => ARRAY['product', 'sentiment'],
model => 'my-chat'
);
SELECT azure_ai.generate(
prompt => 'Summarize this incident report.',
model => 'my-chat'
);
After:
SELECT ai.extract(
text => 'The headphones sound great.',
data => ARRAY['product', 'sentiment'],
model => 'my-chat'
);
SELECT ai.generate(
prompt => 'Summarize this incident report.',
model => 'my-chat'
);
The ai.extract() function requires a non-NULL data array, even though its SQL declaration provides a NULL default. For generation, if you omit json_schema, the function returns text; if you supply json_schema, it returns jsonb. If you supply max_tokens, also supply model and system_prompt. See the current AI function signatures.
Migrate reranking and result handling
Before:
SELECT *
FROM azure_ai.rank(
query => 'headphones for travel',
document_contents => ARRAY['Foldable headphones', 'Desktop speakers'],
document_ids => ARRAY[101, 102],
model => 'my-reranker'
);
After:
SELECT id, rank, score
FROM ai.rank(
query => 'headphones for travel',
data => ARRAY['Foldable headphones', 'Desktop speakers'],
ids => ARRAY[101, 102],
top_n => 2,
model => 'my-reranker'
);
Keep texts and IDs in matching order. The ai.rank() function returns id, rank, and score. When you supply ids, id uses the supplied array's element type; when you don't supply ids, id is the zero-based input-document index. If an older application or example expects document_id or relevance_score, update its projections and joins to match the actual installed result shape. Some legacy builds already return id, rank, and score; inspect the catalog rather than assuming a result-column rename is always necessary.
Migrate pipeline-creation SQL separately
The ai schema also contains pipeline builders. These builders return JSONB descriptors for deferred execution, not direct-inference results:
| Earlier builder | Builder for the current documentation |
|---|---|
ai.embed(input => ...) |
ai.embed_step(input => ...) |
ai.generate(input => ...) |
ai.generate_step(input => ...) |
ai.extract(input => ...) |
ai.extract_step(input => ...) |
ai.rank(input => ...) |
ai.rank_step(input => ...) |
ai.is_true(input => ...) |
ai.is_true_step(input => ...) |
ai.chunk(input => ...) |
ai.chunk_step(input => ...) |
input identifies a source or prior-step column in a pipeline. For immediate embedding inference, use ai.embed(text => ...); for a deferred embedding step, use ai.embed_step(input => ...). Don't replace one with the other in an UPDATE or similarity query.
You don't need to recreate existing stored pipeline descriptors and source or sink tables for the builder rename. ai.deduplicate(), source and sink helpers, and pipeline management functions keep their names. For examples, see AI pipeline upgrade guidance.
Validate and roll out application changes
- Inventory callers, including application SQL, stored routines, scheduled jobs, ingestion scripts, and new pipeline definitions. Use the catalog query to check each target database; it doesn't discover SQL stored in external applications.
- Test the extension upgrade and rewritten calls in a nonproduction database with the same model aliases and permissions.
- Verify vector dimensions and casts, batch result handling, extraction labels, reranker ID types and joins, and callers that depend on retry or error behavior. Compare model output behavior without requiring byte-for-byte identical generative responses.
- Deploy migrated callers incrementally. Monitor failures, latency, throttling, and retry behavior by using your existing application and database monitoring.
- Keep the previous application SQL available during rollout. Because legacy inference functions remain available in 2.5.6, reverting a caller doesn't require downgrading the extension. This condition isn't a guarantee about future releases.