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

[prshri-msft]

Implements #3331 — Parameter Substitution.

Closes #3331.

What this PR adds

A new embed: true flag for stored-procedure parameters. When the flag is set, DAB:

1. Receives plain text from the user (REST POST body, REST GET query string, or GraphQL argument)
2. Calls the IEmbeddingService (introduced in Enable internal text embedding API  #3441) to convert text → vector embedding
3. Substitutes the serialized vector into the @param value passed to the stored procedure
4. The procedure runs VECTOR_DISTANCE (or any other VECTOR-shaped logic) and returns results

This enables a single-call semantic-search API surface: the client sends free text, DAB handles the embedding, the database does the vector match.

Example

Config:

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

The target stored procedure must declare @query_vector VECTOR(N) (e.g., VECTOR(1536)):

CREATE PROCEDURE dbo.SearchProducts
    @query_vector VECTOR(1536),
    @top_k INT = 5
AS
BEGIN
    SELECT TOP(@top_k) Id, Name, Description, VECTOR_DISTANCE('cosine', embedding, @query_vector) AS Distance
    FROM dbo.Products
    ORDER BY Distance ASC
END

Request:

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

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

Response: ranked products via the procedure's VECTOR_DISTANCE semantic match.

Implementation overview

Area	Change
Config	New embed boolean property on ParameterMetadata; documented in JSON schema.
Validation	New ValidateEmbedParameters in RuntimeConfigValidator enforces 4 rules at startup: (0) MSSQL data sources only, (1) stored-procedure entities only, (2) runtime.embeddings must be configured + enabled, (3) cannot be combined with a default value.
DI wiring	SqlQueryEngine, SqlMutationEngine, and their factories accept an optional IEmbeddingService?. Existing engines without embed params work unchanged (null service is fine when no embed params exist).
Substitution	New ParameterEmbeddingHelper.SubstituteEmbedParametersAsync — three-phase Collect → Batch → Substitute pipeline. Uses TryEmbedBatchAsync so multi-embed-param sprocs make a single API call instead of N sequential ones.
Metadata override	MsSqlMetadataProvider overrides VECTOR(N) sproc params (reported as Byte[] by SQL Server's INFORMATION_SCHEMA.PARAMETERS) to flow through DAB's String type pipeline. SQL Server auto-casts NVARCHAR → VECTOR at execution. Non-VECTOR params with embed: true are rejected at startup with a clear error.
Float serialization	Vectors are serialized using G9 format with InvariantCulture to guarantee round-trip precision and locale independence.

Test coverage

44 new unit tests added across 3 files. All pass cleanly.

File	New tests	What's covered
src/Service.Tests/UnitTests/ParameterEmbeddingHelperTests.cs (new)	28	All behaviors of SubstituteEmbedParametersAsync: no-op cases, service availability, input type validation (string + JsonElement variants), empty/whitespace rejection, single-and-multi batching, batch result handling (success/failure/length mismatch/empty individual vector), G9 + InvariantCulture output format, cancellation token forwarding
src/Service.Tests/UnitTests/ConfigValidationUnitTests.cs (extended)	10	All 4 startup validation rules + multi-entity error message specificity (only the offending entity is named)
src/Service.Tests/UnitTests/SqlMetadataProviderUnitTests.cs (extended)	6	ApplyEmbedTypeOverride helper: Byte[]+embed:true overridden, non-Byte[]+embed:true throws at startup, embed:false untouched, multi-param scenarios

Run with:

dotnet test src/Service.Tests --filter "FullyQualifiedName~ParameterEmbeddingHelperTests|FullyQualifiedName~ValidateEmbedParameters|FullyQualifiedName~ApplyEmbedTypeOverride"

Manual end-to-end verification

Beyond the unit tests, the feature was manually verified against a live Azure SQL database (with VECTOR(1536) sproc) and Azure OpenAI (text-embedding-3-small). 16+ scenarios across REST POST, REST GET, and GraphQL — covering positive cases (single + multi-embed-param sprocs), input validation negatives (empty, whitespace, non-string types), and missing-param cases.

Prior review history (while #3441 was still in flight): 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.