Phase 3: Stored Procedure Parameter Substitution (auto-embed: true)

[prshri-msft]

Implements #3331. Closes #3331.

What this PR adds

A new auto-embed: true flag for stored-procedure parameters. DAB acts as a string-substitution layer: takes plain text from the caller, calls IEmbeddingService for the vector, serializes it to a JSON array string ("[0.012,-0.045,...]"), and substitutes it as the parameter value. The sproc receives a string-compatible parameter (NVARCHAR/VARCHAR) and owns any CAST(... AS VECTOR(N)) itself.

Single-call semantic search: client sends free text → DAB embeds → DB matches.

Example

// entities: { ... }
"SearchProducts": {
  "source": {
    "type": "stored-procedure",
    "object": "dbo.SearchProducts",
    "parameters": [
      { "name": "query_text", "auto-embed": true },
      { "name": "top_k", "default": "5" }
    ]
  },
  "rest": { "enabled": true, "methods": ["post"] },
  "permissions": [{ "role": "anonymous", "actions": [{ "action": "execute" }] }]
}

Schema accepts boolean-or-string, so "auto-embed": "@env(ENABLE_EMBED)" is also valid.

CREATE PROCEDURE dbo.SearchProducts
    @query_text NVARCHAR(MAX),
    @top_k INT = 5
AS
BEGIN
    DECLARE @v VECTOR(1536) = CAST(@query_text AS VECTOR(1536));
    SELECT TOP(@top_k) Id, Name, VECTOR_DISTANCE('cosine', embedding, @v) AS Distance
    FROM dbo.Products
    ORDER BY Distance ASC;
END

POST /api/SearchProducts
Content-Type: application/json

{ "query_text": "wireless headphones", "top_k": 3 }

Implementation

• Config: auto-embed on ParameterMetadata; boolean-or-string in schema.
• Validation: 2 startup rules — stored-procedure entities only; runtime.embeddings must be configured. Per-MSSQL string-compatibility check rejects non-string sproc params (VECTOR, INT, …) at startup.
• DI: IEmbeddingService is non-optional. NullEmbeddingService.Instance registered when embeddings are not configured.
• Substitution: ParameterEmbeddingHelper.SubstituteEmbedParametersAsync runs Collect → Batch → Substitute. Defaults are honored; null/empty/whitespace → string.Empty (no API call); non-string runtime values → 400. All auto-embed params for one entity batch into a single TryEmbedBatchAsync call.
• CLI: --parameters.auto-embed on dab add / dab update; preserved across updates.
• API metadata: auto-embed surfaced in OpenAPI, GraphQL, and MCP describe-entities.
• Telemetry: Meter DataApiBuilder.AutoEmbedSubstitution (2 counters + 1 histogram) + Activity AutoEmbed.Substitute. Tags: entity, sproc, param_names, embedding.provider, embedding.model, outcome, duration_ms. Never includes input text or vector values (spec data-safety requirement).
• HTTP status codes (per spec § Error behavior):
  • 400 non-string input
  • 502 provider call failed or returned malformed response (empty vector / wrong count)
  • 503 embedding subsystem unavailable
  • 500 reserved for DAB-internal bugs
• Vector format: G9 + InvariantCulture for round-trip precision.

Tests

54+ new unit tests, all passing in CI:

• ParameterEmbeddingHelperTests (34) — full substitution helper + telemetry coverage
• ConfigValidationUnitTests (10) — startup rules
• SqlMetadataProviderUnitTests (6) — string-compatibility check
• ConfigurationTests, DescribeEntitiesStoredProcedureParametersTests, CLI tests — config round-trip + MCP metadata + CLI parsing

dotnet test src/Service.Tests --filter "FullyQualifiedName~ParameterEmbeddingHelperTests|FullyQualifiedName~ValidateAutoEmbed|FullyQualifiedName~DescribeEntitiesStoredProcedureParametersTests|FullyQualifiedName~AutoEmbedParam_Description"
dotnet test src/Cli.Tests --filter "FullyQualifiedName~AutoEmbed"

Manually verified end-to-end against live Azure SQL + Azure OpenAI (text-embedding-3-small): REST POST/GET, GraphQL, MCP execute-entity; single + multi-embed-param sprocs; positive paths + input-validation + provider-failure cases.

Notable design decisions

• DAB is a string substitution layer, not a type-coercion engine. Earlier iterations rewrote sproc parameter type from VECTOR to String at metadata discovery. Per spec, the sproc declares the param as a string type and DAB never touches sproc metadata.
• Provider-neutral. Original PR was MSSQL-only at the validator level; per spec, no DB-type gate. Per-provider string checks live in the provider's metadata code.
• Defaults are honored. Original PR rejected auto-embed + default; per spec, defaults are allowed and embedded when the caller omits the param.
• Renamed embed → auto-embed to clarify DAB does the embedding on the caller's behalf.
• NullEmbeddingService null-object moves the "is this configured?" check into IsEnabled; DI misconfiguration now fails at startup instead of producing NullReferenceException at first request.

---

Prior review history (during #3441): ajtiwari07/data-api-builder#1.

[Copilot]

Pull request overview

Adds “Phase 3” support for stored-procedure parameter substitution via embeddings by introducing an embed: true flag on sproc parameters. At runtime, DAB converts user-provided text into an embedding vector using IEmbeddingService and substitutes the serialized vector into the sproc parameter value before execution (MSSQL only), with startup validation and unit tests covering key behaviors.

Changes:

• Extend config/schema to support parameters[].embed and validate correct usage at startup (MSSQL + stored-proc only, embeddings enabled, no defaults).
• Add ParameterEmbeddingHelper.SubstituteEmbedParametersAsync and wire it into REST + GraphQL stored-procedure execution paths.
• Override MSSQL VECTOR parameter metadata (reported as byte[]) to flow through the string pipeline, plus add unit tests for type override and substitution logic.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/Service.Tests/UnitTests/SqlMetadataProviderUnitTests.cs	Adds unit tests for MSSQL VECTOR param type override behavior when embed: true is set.
src/Service.Tests/UnitTests/ParameterEmbeddingHelperTests.cs	New comprehensive unit tests for batching, validation, formatting, and cancellation in parameter embedding substitution.
src/Service.Tests/UnitTests/ConfigValidationUnitTests.cs	Adds unit tests for startup validation rules governing embed: true usage.
src/Core/Services/MetadataProviders/MsSqlMetadataProvider.cs	Applies and exposes ApplyEmbedTypeOverride to validate/override VECTOR-shaped parameters for embedding substitution.
src/Core/Services/Embeddings/ParameterEmbeddingHelper.cs	Implements the collect → batch → substitute pipeline to embed text parameters into vector JSON strings.
src/Core/Resolvers/SqlQueryEngine.cs	Wires embedding substitution into GraphQL sproc execution and REST sproc execution.
src/Core/Resolvers/SqlMutationEngine.cs	Wires embedding substitution into REST stored-procedure mutation execution.
src/Core/Resolvers/Factories/QueryEngineFactory.cs	Passes optional IEmbeddingService into SqlQueryEngine.
src/Core/Resolvers/Factories/MutationEngineFactory.cs	Passes optional IEmbeddingService into SqlMutationEngine.
src/Core/Configurations/RuntimeConfigValidator.cs	Adds ValidateEmbedParameters startup validation invoked during config validation.
src/Core/Azure.DataApiBuilder.Core.csproj	Adds InternalsVisibleTo to allow direct unit testing of new internal helpers.
src/Config/ObjectModel/ParameterMetadata.cs	Adds the Embed property and XML docs to parameter metadata.
schemas/dab.draft.schema.json	Adds embed to the JSON schema for stored-procedure parameter metadata.

[JerryNixon]

Spec mismatches

Acceptance criteria

Issue	Current PR behavior	Required change
Property name	Uses embed	Rename the property to auto-embed
@env() and @akv() support	Schema is plain boolean; runtime is bool	Change the schema to boolean-or-string and resolve @env() / @akv() at config load
Type rule	Requires VECTOR(N) / Byte[]; rejects strings	Validate that the target parameter is string-compatible, such as nvarchar or varchar; reject VECTOR
Provider scope	Hard-fails non-MSSQL at startup	Remove the MSSQL gate. Treat embedding as a provider-neutral string-substitution step
Default values	Rejects embed: true plus default at startup	Allow defaults and embed them when the caller omits the parameter
Empty, whitespace, or null input	Returns 400	Skip embedding and pass "" to the stored procedure
Missing parameter name	Typo in config is silently ignored	Validate that each auto-embed parameter name exists on the entity and fail startup otherwise
CLI support	No --parameters.auto-embed in dab add or dab update	Add the option to both commands
Metadata	Not exposed in OpenAPI, GraphQL, or MCP describe	Surface auto-embed in OpenAPI schema, GraphQL SDL or description, and MCP tool description
Telemetry	No logs or OTEL in ParameterEmbeddingHelper	Add structured logs and OTEL spans or metrics around embedding calls, including latency, success or failure, and provider
MCP support	No MCP test; verification covers REST and GraphQL only	Add an MCP integration test and document MCP verification steps

Behavior bugs

Issue	Current PR behavior	Required change
Status codes	Provider or batch failure returns 500	Map provider errors to 502; map unavailability or timeout to 503
Provider error details	Drops batchResult.ErrorMessage	Propagate provider status, provider code, sanitized message, and correlation ID
Optional DI dependency	IEmbeddingService? = null allows DI misconfiguration to fail on first request	Make the dependency non-optional and register a null-object IEmbeddingService when embeddings are disabled
Hot reload	Validator reruns, but ApplyEmbedTypeOverride only runs at init	Rerun ApplyEmbedTypeOverride on hot reload and add a hot-reload test
Spec-conflicting tests	Tests lock in rejected defaults and 400 for null or empty values	Update tests to assert defaults are embedded and null, empty, or whitespace values pass ""

Nits

Issue	Required change
Schema description leaks implementation limitation	Move the caveat to docs and keep the schema description user-facing
using ...Embeddings; out of sort order in 4 files	Run dotnet format --verify-no-changes and fix using order
Entity lookup duplicated at 3 call sites	Extract a helper method and call it from the three sites

[prshri-msft]

Spec mismatches

Acceptance criteria

Issue Current PR behavior Required change
Property name Uses embed Rename the property to auto-embed
@env() and @akv() support Schema is plain boolean; runtime is bool Change the schema to boolean-or-string and resolve @env() / @akv() at config load
Type rule Requires VECTOR(N) / Byte[]; rejects strings Validate that the target parameter is string-compatible, such as nvarchar or varchar; reject VECTOR
Provider scope Hard-fails non-MSSQL at startup Remove the MSSQL gate. Treat embedding as a provider-neutral string-substitution step
Default values Rejects embed: true plus default at startup Allow defaults and embed them when the caller omits the parameter
Empty, whitespace, or null input Returns 400 Skip embedding and pass "" to the stored procedure
Missing parameter name Typo in config is silently ignored Validate that each auto-embed parameter name exists on the entity and fail startup otherwise
CLI support No --parameters.auto-embed in dab add or dab update Add the option to both commands
Metadata Not exposed in OpenAPI, GraphQL, or MCP describe Surface auto-embed in OpenAPI schema, GraphQL SDL or description, and MCP tool description
Telemetry No logs or OTEL in ParameterEmbeddingHelper Add structured logs and OTEL spans or metrics around embedding calls, including latency, success or failure, and provider
MCP support No MCP test; verification covers REST and GraphQL only Add an MCP integration test and document MCP verification steps

Behavior bugs

Issue Current PR behavior Required change
Status codes Provider or batch failure returns 500 Map provider errors to 502; map unavailability or timeout to 503
Provider error details Drops batchResult.ErrorMessage Propagate provider status, provider code, sanitized message, and correlation ID
Optional DI dependency IEmbeddingService? = null allows DI misconfiguration to fail on first request Make the dependency non-optional and register a null-object IEmbeddingService when embeddings are disabled
Hot reload Validator reruns, but ApplyEmbedTypeOverride only runs at init Rerun ApplyEmbedTypeOverride on hot reload and add a hot-reload test
Spec-conflicting tests Tests lock in rejected defaults and 400 for null or empty values Update tests to assert defaults are embedded and null, empty, or whitespace values pass ""

Nits

Issue Required change
Schema description leaks implementation limitation Move the caveat to docs and keep the schema description user-facing
using ...Embeddings; out of sort order in 4 files Run dotnet format --verify-no-changes and fix using order
Entity lookup duplicated at 3 call sites Extract a helper method and call it from the three sites

Thanks for the thorough review, @JerryNixon
I had a few clarifying questions before I push the remaining changes that you requested

The "type rule", "provider scope", "default values", and "empty/whitespace/null input" items together represent a meaningful redesign relative to what's currently in the PR.

1. Re: type rule (NVARCHAR/VARCHAR target instead of VECTOR) — For sprocs receiving NVARCHAR-typed embed params, do you envision sproc authors writing an explicit DECLARE @vec VECTOR(N) = CAST(@param AS VECTOR(N)) in the sproc body, or do you expect SQL Server's implicit conversion in VECTOR_DISTANCE(..., @param) to handle it transparently?

2. Re: allowing defaults + embedding them — In an earlier iteration of this PR we deliberately rejected auto-embed: true + default after analyzing the UX (a missing search query usually indicates a client bug rather than intent to fall back to a canned semantic search). Curioius to learn about the design decision behind supporting default values

3. Re: empty / whitespace / null input → skip embedding, pass "" — Should null be normalized to "" for the sproc, or remain distinct (bind as DBNull)? And for non-string inputs supplied where an auto-embed param is expected (e.g., a number), do you still want a 400, or also pass through as ""?

4. Re: missing parameter name validation — MsSqlMetadataProvider already throws Could not find parameter 'X' specified in config for procedure 'Y' at startup when the param name doesn't match any sproc parameter (assuming the DB is reachable). Are you referring to a dab validate CLI scenario where the DB isn't reachable, or a different gap you've seen?

[souvikghosh04]

mostly refactorings, minor suggestions and nits. also, check the startup validation