(ignore) Add Azure SQL vector search sample constitution - #1515
Open
Dina Berry (MSFT) (diberry) wants to merge 8 commits into
Open
Dina Berry (MSFT) (diberry) wants to merge 8 commits into
Dina Berry (MSFT) (diberry) wants to merge 8 commits into
Conversation
Adds .github/instructions/vector-search-constitution.instructions.md, scoped via applyTo to samples/features/vector-search/**. Converts the approved plan (plan-2026-07-01-0842-azure-sql-vector-search-quickstart.pdf, comments PK1-PK8/DB2R1) into repository-local technical/sample governance: - Article 1: program-wide requirements (platform scope, dataset provenance and CELA gate, auth/security, infra, cross-language parity, validation, contribution acceptance criteria). - Article 2: the vector search scenario, including the exact-kNN vs DiskANN algorithm gate and the >=1,000-row DiskANN requirement, which the current 50-hotel dataset does not meet (the merged sample falls back to exact automatically below that threshold). - Article 3: language-specific requirements. TypeScript (microsoft#1479) is documented as the only implemented reference; .NET, Python, Java, and Go are explicit target contracts, not implemented, per the plan. Documents five source conflicts (language priority, TypeScript VECTOR support, dataset CELA approval, MI DiskANN support, platform priority) rather than silently resolving them. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…nstitution Addresses feedback on microsoft#1515: the constitution covered only TypeScript in Article 3, with .NET/Python/Java left as vague OPEN placeholders. The constitution must determine language requirements before samples are produced, not defer them. - Article 3 (.NET, Python, Java) now specifies, per language: runtime and package version baseline, authentication pattern, centralized configuration/env-var contract (parity with the TypeScript reference), vector parameter binding (JSON-cast default, matching the plan's verified-against-Learn snippets), bulk-insert pattern, the DiskANN row-count gate (identical logic to ASV-VS-4), package-manager convention, sample-folder name, and a CI workflow shape mirroring vector-search-typescript-ci.yml. - Version pins with no plan evidence (.NET net10.0, Python 3.13, Java 21) are recorded as explicit constitution-author decisions, distinct from implementation evidence, with rationale. - Only two true unknowns remain flagged OPEN without blocking the rest of each contract: the Microsoft.Data.SqlClient version needed for native SqlVector<float> binding (.NET), and the exact mssql-jdbc Azure AD connection-property name/version (Java). - Added ASV-CORE-29/30 to Article 1: sample-folder naming (vector-search-query-<language>) and default table-name convention (hotels_<language>) so multiple languages can coexist without collisions. - Go is unchanged: still explicitly out of scope, since the source plan provides no driver/auth evidence to specify a Go contract from. - Re-validated: 71 internal anchor links resolve, 85 unique requirement IDs with no dangling references, fences balanced. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
Author
|
Updated the constitution to address the "only TypeScript" gap: ASV-LANG-NET-1 through 12, ASV-LANG-PY-1 through 12, and ASV-LANG-JAVA-1 through 11 now fully determine each language's runtime/package baseline, auth pattern, config/env-var contract, vector parameter binding, bulk-insert pattern, the DiskANN row-count gate, package-manager convention, sample-folder naming, and CI shape — so a sample can be implemented directly against the constitution rather than waiting on further design decisions. Go remains out of scope (no driver/auth evidence in the source plan to specify a contract from). Only two narrow items stay OPEN (native SqlVector binding version for .NET; exact mssql-jdbc Azure AD property/version for Java) and neither blocks starting implementation. |
…constitution Per request: add a Go section even though Go coverage isn't currently required, so a future contributor has a determined contract to build from rather than a bare exclusion. Unlike .NET/Python/Java, the source plan provides zero driver, auth, or code evidence for Go (PDF p.3 marks it "future/optional... out of scope for v1"). Rather than invent specifics, every new requirement (ASV-LANG-GO-2 through ASV-LANG-GO-14) is sourced from live, verified documentation for the actual Go ecosystem, fetched 2026-09-15: - github.com/microsoft/go-mssqldb (pure Go database/sql driver; requires Go 1.25+; latest tag v1.11.0, 2026-08-24). - github.com/microsoft/go-mssqldb/azuread (registers driver name "azuresql"; DSN parameter fedauth=ActiveDirectoryDefault confirmed by reading driver.go/configuration.go at tag v1.11.0). - github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai (Azure OpenAI Go SDK, confirmed to exist at v0.9.0) for the query embedding. No native Go VECTOR parameter-binding type was found in any of this research, so the vector-binding requirement (ASV-LANG-GO-8) specifies the same JSON-cast fallback used for .NET/Python/Java, and ASV-LANG-GO-14 flags that absence as OPEN rather than asserting an unconfirmed capability. ASV-LANG-GO-1 is preserved and clarified: having a determined contract does not itself bring Go into scope for this v1 scenario — that still requires a separate, explicit decision. Also: fixed a stale internal anchor link in ASV-CORE-29 left over from the prior commit's heading rename (old Go section slug), and added a §7 evidence-log row documenting the Go research. Re-validated: 93 internal anchor links resolve, 98 unique requirement IDs with no dangling references, fences balanced. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
Author
|
Added a fully specified Go section per request, even though Go isn't currently required for coverage — ASV-LANG-GO-1 through ASV-LANG-GO-14. Since the source plan gives zero Go evidence (it only says "future/optional... out of scope for v1"), every new requirement instead cites live, independently verified documentation for the real Go ecosystem (fetched today): github.com/microsoft/go-mssqldb (driver, requires Go 1.25+, latest tag �1.11.0), its �zuread subpackage (confirmed edauth=ActiveDirectoryDefault DSN parameter and �zuresql driver name by reading the actual source at that tag), and github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai (confirmed to exist at �0.9.0) for the query embedding. No native Go VECTOR parameter-binding type was found anywhere in that research, so the constitution specifies the same JSON-cast fallback used for .NET/Python/Java rather than asserting an unconfirmed capability, and flags that gap as OPEN. ASV-LANG-GO-1 is preserved: having a determined contract does not itself put Go in scope for this v1 scenario — that still needs a separate, explicit decision. Re-validated: 94 internal anchor links resolve, 98 unique requirement IDs with no dangling references. |
Section 1's summary sentence listed .NET, Python, Java, and Go as the languages Article 3 specifies, but omitted TypeScript — the one language that is actually implemented. Corrected the sentence to list all five languages and clarify that TypeScript's contract is Evidence: implemented (the merged reference sample) while .NET, Python, Java, and Go are determined but not yet built. Re-validated: 94 internal anchor links resolve, 98 unique requirement IDs with no dangling references, fences balanced. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… constitution Per request: ASV-CORE-3 discussed platform scope in prose only, listing which of the four named platforms have shipped, without a table cross-referencing platform to language support. Checked the source plan PDF directly for an existing platform x language table (re-extracted with pdfplumber's table detection on the platform/language pages; only comment-balloon boxes were misdetected as tables, no genuine grid was found there). The plan does contain one real table relevant to platforms -- "the whole quickstart in one table" (PDF p.9-10), drafted against the .NET build-out with the note that Python mirrors the same steps via pyodbc. That table is per platform x concern (provision/auth/preview/exact-kNN/ANN/cleanup), not per platform x language, so I: 1. Reproduced that plan table verbatim under ASV-CORE-3, properly cited to PDF p.9-10, as supporting evidence for why a platform switch is not a drop-in change. 2. Added ASV-CORE-31: a new platform x language current-status matrix, explicitly labeled Decision: this constitution (a synthesis of already-cited ASV-CORE-2/3 and Article 3 facts, not new evidence). It shows every language's contract is currently scoped to Azure SQL Database only; no platform besides Azure SQL Database has any language in scope yet. Also folded in a changelog entry for the earlier TypeScript-list fix that shipped without one, per this constitution's own §0.4 amendment rule. Re-validated: 113 internal anchor links resolve, 99 unique requirement IDs with no dangling references, fences balanced. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…eculation Two changes per request: 1. ASV-CORE-21's captured "Expected output" must now also be committed as a plain-text reference file under the sample's own output/ subfolder (e.g. output/sample-output.txt), matching the source plan's own instruction (PDF p.13) to commit that file "for the verification script to assert against." Added a carve-out to ASV-CORE-11 so .gitignore no longer excludes this file wholesale, and added CONF-6: the merged TypeScript sample's .gitignore currently ignores output/ in its entirety with no such file committed -- the plan's intent was not carried into the shipped implementation, so this is a forward-looking requirement (including a follow-up fix needed for TypeScript itself), not evidence of something already done. 2. Removed forward-looking speculation about a hypothetical future second scenario from ASV-CORE-29 (folder naming) and the document preamble's Canonical scenario line -- including the parallel drawn to the sibling Cosmos DB repo's create-index scenario. This constitution covers the first vector search scenario only; a second scenario can be added to this document later rather than speculated about now. ASV-CORE-29 still correctly notes the folder name vector-search-query-<language-slug> encodes the scenario (query) as well as the language, just without describing an unratified future scenario 2. Re-validated: 129 internal anchor links resolve, 100 unique requirement IDs with no dangling references, fences balanced. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ction
TypeScript uses a .env file; .NET idiomatically uses appsettings.json,
not .env -- the constitution previously implied every language should
mirror TypeScript's plain-environment-variable approach
(ASV-LANG-NET-4 said "centralize environment-variable loading...
parity with src/config.ts"), which is wrong for .NET.
Verified live against github.com/Azure-Samples/cosmos-db-vector-samples
(fetched 2026-09-15), a sibling Microsoft sample repo shipping the same
five languages:
- nosql-vector-search-dotnet/Program.cs + appsettings.json: loads
config via ConfigurationBuilder().AddJsonFile("appsettings.json").
AddEnvironmentVariables(), bound to a strongly-typed record. Its
.gitignore commits appsettings.json itself (placeholder values, no
secrets -- auth is Entra/managed-identity) and only ignores
appsettings.local.json / appsettings.Development.json.
- nosql-vector-search-python/sample.env and nosql-create-index-java's
Config.java confirm Python/Java/Go all use a .env file instead,
matching the already-implemented TypeScript pattern.
Changes:
- Added ASV-CORE-33: no single universal config-file format across the
five languages; per-language mechanism/template/gitignore table.
- Added ASV-CORE-34: matching .gitignore rule, including that
appsettings.json itself must not be excluded.
- Rewrote ASV-LANG-NET-4 into a fully specified appsettings.json +
Microsoft.Extensions.Configuration contract (nested JSON keys,
ASP.NET Core double-underscore env-var override convention).
- Updated ASV-LANG-PY-4/JAVA-4/GO-6 to cross-reference ASV-LANG-TS-3
(the shared .env-based parity anchor) instead of ASV-LANG-NET-4,
since .NET is no longer a valid .env parity anchor.
- Added an evidence-log row documenting the cosmos-db-vector-samples
research.
Re-validated: 153 internal anchor links resolve, 102 unique
requirement IDs with no dangling references, fences balanced.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Per directive: "the constitution should state and link to the SDK package that the language will use to query the service - this should also be in the pdf/word doc." Verified the PDF first, then verified currency against official package sources; did not call every driver an Azure SDK. Added three separate tables (ASV-CORE-35/36/37) instead of one combined list, since the directive requires separating the SQL query driver from Azure Identity and Azure OpenAI packages: - Role 1 (SQL driver): tedious (TS, implemented), Microsoft.Data.SqlClient (.NET, PDF p.2 + comment PK3), pyodbc (Python, PDF p.2-3 + comment PK4), com.microsoft.sqlserver:mssql-jdbc (Java, PDF p.3 + comment PK5, Maven Central latest 12.10.0.jre11), github.com/microsoft/go-mssqldb (Go, no PDF evidence -- verified live). - Role 2 (Azure Identity): @azure/identity (TS, implemented), Azure.Identity (.NET, named only parenthetically in PDF p.2), azure-identity (Python, PDF p.3), com.azure:azure-identity (Java, not in PDF -- verified live, Maven latest 1.16.2), azidentity (Go). - Role 3 (embeddings): openai package's AzureOpenAI class (TS/Python -- explicitly NOT an Azure SDK package, it's OpenAI's own SDK with built-in Azure support), Azure.AI.OpenAI (.NET), com.azure:azure-ai-openai (Java), azopenai (Go). No language's OpenAI package is named in the PDF -- only the embedding model name (text-embedding-3-small, p.16). Two currency findings not in the plan, surfaced by verifying against official registries (NuGet/PyPI/Maven Central) on 2026-09-15: - Microsoft.Data.SqlClient v7.0+ requires the separate Microsoft.Data.SqlClient.Extensions.Azure package for connection- string Entra auth keywords like Authentication=Active Directory Default. - Azure.AI.OpenAI (.NET) and com.azure:azure-ai-openai (Java) are both prerelease/beta-only on their registries with no GA release -- marked OPEN - decision required rather than silently pinned. Added ASV-CORE-38: sample manifests/imports must match the table's package identity; a PR changing one of these packages must update the table in the same PR. Corrected terminology throughout: SQL drivers are called drivers, not "Azure SDK"; the openai package is called the OpenAI client library (published by OpenAI, not Microsoft), not an Azure SDK package. Updated ASV-LANG-TS-2, NET-2/3, PY-2/3, JAVA-2/3, and GO-3/4/5 to cross-reference the new tables and fill genuine gaps (Java previously named no Identity/OpenAI package at all; .NET/Python didn't name their OpenAI package). Recorded the directive itself, and what the PDF actually says, in the evidence log (Section 7), plus a row citing every live package-source verification performed. Re-validated: 193 internal anchor links resolve, 106 unique requirement IDs with no dangling references, fences balanced. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
Author
|
Added explicit, per-language service-query package requirements per directive. Verified the PDF first. It names: Microsoft.Data.SqlClient for .NET (p.2, comment PK3), pyodbc for Python (p.2-3, comment PK4), and the Microsoft JDBC Driver for SQL Server for Java (p.3, comment PK5) as SQL drivers. It names Azure.Identity only parenthetically for .NET (p.2) and �zure-identity explicitly for Python (p.3). It never names a specific Azure OpenAI package for any language, or any package at all for Go — only the embedding model name ( ext-embedding-3-small, p.16). Every package not named in the PDF was verified live against its official registry (NuGet/PyPI/Maven Central/pkg.go.dev) on 2026-09-15 rather than guessed — see ASV-CORE-35/36/37 for three separate tables (SQL driver / Azure Identity / embeddings), each with package name, canonical URL, status, version policy, and locator, and ASV-CORE-38 requiring manifests/imports to match. Two currency findings not in the plan surfaced during verification, both flagged rather than silently pinned:
Terminology corrected throughout: SQL drivers ( edious, Microsoft.Data.SqlClient, pyodbc, mssql-jdbc, go-mssqldb) are called drivers, not "Azure SDK"; the openai package is called the OpenAI client library (published by OpenAI, not Microsoft), since it is not itself an Azure SDK package even though it includes Azure OpenAI support. |
This was referenced Sep 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Converts the approved plan (plan-2026-07-01-0842-azure-sql-vector-search-quickstart.pdf, source: Teams meeting "Azure SQL + Vector DB quickstarts", 2026-07-01, with reviewer comments from Pooja Kamath and Dina Berry) into repository-local technical/sample governance at .github/instructions/vector-search-constitution.instructions.md, scoped via �pplyTo: samples/features/vector-search/**.
This is internal guidance for future sample implementation and review — not a Microsoft Learn article and not editorial content.
What it covers
Source reconciliation
The constitution reconciles the source plan against:
Five source conflicts are documented rather than silently resolved (see the constitution's "Conflicts and open decisions" section): language priority order, TypeScript VECTOR/managed-identity support, dataset CELA/hosting approval, Managed Instance DiskANN support, and platform priority if not all four flavors ship.
Validation performed
Scope
Adds one new file under .github/. No sample code, infra, tests, or CI is changed.
🤖 Generated by an AI agent (aidba, project-dina) on behalf of Dina Berry (MSFT) (@diberry). Internal governance change — no customer-facing content.