Saturday, September 19, 2026

Azure AI Search Vector Settings — Simple Guide

Azure AI Search Vector Settings
explained simply

Every important setting, what it does, and why you would change it — based on the official Microsoft docs.

What is a vector index in Azure AI Search?

Azure AI Search (formerly Azure Cognitive Search) can store and search vector embeddings — long lists of numbers that represent the meaning of text or images.

To make vector search work you configure three layers:

  1. Vector fields — where the numbers live
  2. Algorithms + parameters — how the search engine finds similar vectors
  3. Profiles + compressions — which algorithm + optional size reduction each field uses
Think of it like a library: the field is the shelf, the algorithm is how the books are organized, and the profile is the rule card that says “this shelf uses this organization method.”

Basic terminology (in plain English)

TermSimple meaning
Embedding / Vector A long list of numbers that captures the meaning of text (or an image). Similar meanings → similar numbers.
Dimensions How many numbers are in each vector (e.g. 1536). Fixed by the embedding model.
Index The “database” in Azure AI Search. Holds documents and their vectors.
Document One row / record in the index (like a product, article, or support ticket).
Field A column on the document (title, content, contentVector, etc.).
Nearest Neighbor Finding the vectors that are closest (most similar) to your query vector.
HNSW A smart graph structure that finds nearest neighbors fast without checking every vector.
Exhaustive KNN The slow but exact way: compare the query to every vector.
Metric (cosine, etc.) The formula used to measure “how similar” two vectors are.
Quantization / Compression Making the numbers smaller (fewer bits) so the index uses less memory and disk.
Profile A named combo of algorithm + compression that you attach to a vector field.
k How many nearest neighbors you want back (top-k results).
Hybrid search Combining classic keyword search + vector search in one query.

Azure AI Search vs SQL — the simple comparison

If you already know SQL, this table maps the ideas.

SQL conceptAzure AI Search equivalentKey difference
Database Search service A service that can host many indexes.
Table Index Schema is more flexible; designed for search, not transactions.
Row Document JSON-like document, not a rigid row.
Column Field Fields have search behaviors (searchable, filterable, retrievable…).
Primary key Key field Every document needs a unique key (usually a string).
CREATE INDEX on a column Making a field searchable / vectorSearchProfile You declare search behavior in the schema itself.
B-tree / hash index HNSW graph (for vectors) HNSW is for high-dimensional similarity, not equality or range.
WHERE column = value Filter (OData filter) Filters work on non-vector fields. Vector fields themselves are not filterable.
ORDER BY column Scoring / ranking Results are ranked by similarity score (or hybrid RRF), not by a column value.
SELECT * retrievable fields You control which fields come back; vectors are often set retrievable=false to save space.
JOIN Not really supported the same way You usually denormalize data into the document.
Full-text search (LIKE / CONTAINS) Searchable text fields + analyzers Much stronger linguistic analysis (stemming, synonyms, etc.).
No direct equivalent Vector field + HNSW This is pure similarity search by meaning — SQL doesn’t do this natively.
Mental model: SQL is great at exact matches, ranges, and joins. Azure AI Search is great at “find me documents that mean something similar to this text” plus keyword search and filters on top.

Tiny side-by-side example

-- SQL mindset
SELECT * FROM Products
WHERE category = 'shoes'
ORDER BY price;

-- Azure AI Search mindset (hybrid)
Search for documents whose contentVector is close to
the embedding of "comfortable running shoes for beginners"
AND category eq 'shoes'
→ ranked by similarity + keyword score

1. Vector field settings

These go on the field itself inside the index schema.

SettingWhat it meansWhy you set it
type Usually Collection(Edm.Single) (float32). Can also be narrower types like float16, int8, or byte (binary). Must match what your embedding model outputs. Narrower types save memory and disk.
dimensions How many numbers are in each vector (e.g. 1536 for text-embedding-ada-002). Must exactly match the embedding model. Wrong value = indexing fails or search is meaningless.
vectorSearchProfile Name of a profile defined in the index (links algorithm + compression). Tells the engine which search method and compression this field uses.
searchable Must be true for vector fields. Only searchable fields participate in vector queries.
retrievable true or false. Controls whether the raw vector numbers are returned in search results. Set false to save disk space if you never need the actual numbers back (most apps don’t).
stored Controls whether the vector is kept for retrieval (related to storage optimization). Turn off when you don’t need to return vectors — can cut vector storage significantly.
Vector fields cannot be filterable, facetable, or sortable. They also cannot have analyzers or synonym maps.

2. Algorithms (how search finds neighbors)

Defined under vectorSearch.algorithms.

AlgorithmWhat it doesWhen to use it
HNSW Builds a hierarchical graph of vectors for Approximate Nearest Neighbor search. Very fast. Almost always. Best for large indexes and low latency.
exhaustiveKnn Brute-force: compares the query to every vector. Exact results, slower. Small indexes, accuracy testing, or when you need perfect recall.

You can index a field with HNSW and still force exhaustive search at query time with "exhaustive": true.

3. HNSW parameters (the knobs)

These live inside hnswParameters.

ParameterWhat it controlsTypical valuesWhy change it
metric How “similarity” is calculated. cosine (most common), euclidean, dotProduct, hamming (binary) Must match your embedding model. Azure OpenAI models → use cosine.
m Number of bi-directional links per node in the graph. 4 – 16 (default often 4) Higher m = better recall, more memory and slower indexing.
efConstruction How thoroughly the graph is built during indexing. 100 – 1000 (common 400) Higher = better quality graph, slower indexing, more memory.
efSearch How thoroughly the graph is searched at query time. 100 – 1000 (common 500) Higher = better recall, higher latency. Trade accuracy vs speed.
Simple rule of thumb: start with the defaults (m=4, efConstruction=400, efSearch=500, metric=cosine). Only tune if you measure and need better recall or lower latency.

4. Compression (make vectors smaller)

Defined under vectorSearch.compressions. Optional but powerful for cost and scale.

SettingWhat it doesWhy use it
scalarQuantization Compresses float values into smaller numbers (usually int8). Big reduction in memory and disk with only small accuracy loss.
binaryQuantization Turns floats into 1-bit values. Even smaller size. Best when you accept a bit more accuracy trade-off.
enableRescoring After fast search on compressed vectors, re-rank top results with original vectors. Recovers most of the accuracy lost by compression.
defaultOversampling How many extra candidates to fetch before rescoring (e.g. 10). Higher = better final ranking, slightly more work.
rescoreStorageMethod preserveOriginals or discardOriginals Keep original vectors for rescoring, or discard them to save more space.

You can also use narrower data types on the field itself and turn off stored / retrievable to save even more.

5. Profiles (the glue)

A profile simply links an algorithm + optional compression (+ optional vectorizer) and gives it a name.

PartRole
nameUnique name you reference from the vector field
algorithmWhich algorithm config to use
compression(Optional) Which compression to apply
vectorizer(Optional) Built-in way to turn text into vectors at query time
{
  "vectorSearch": {
    "algorithms": [
      {
        "name": "hnsw-1",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "compressions": [
      {
        "name": "scalar-quantization",
        "kind": "scalarQuantization",
        "scalarQuantizationParameters": { "quantizedDataType": "int8" },
        "rescoringOptions": {
          "enableRescoring": true,
          "defaultOversampling": 10,
          "rescoreStorageMethod": "preserveOriginals"
        }
      }
    ],
    "profiles": [
      {
        "name": "my-profile",
        "algorithm": "hnsw-1",
        "compression": "scalar-quantization"
      }
    ]
  }
}

Then on the field you just write: "vectorSearchProfile": "my-profile"

6. Query-time settings

SettingWhat it doesWhy use it
k How many nearest neighbors to return. Controls result size. Common values: 3–50.
exhaustive Force brute-force search even on an HNSW field. Useful for accuracy checks or very selective filters.
fields Which vector field(s) to search (up to 10). When you have multiple vector fields.
weight Relative importance of this vector query in hybrid search. Balance vector vs text scores.
vectorFilterMode preFilter (default) or postFilter. preFilter is safer for recall; postFilter can be faster with selective filters.

Quick “why” summary

GoalWhat to change
Better accuracy / recallHigher efSearch, higher m, enable rescoring, or use exhaustive
Faster queries / lower costLower efSearch, use compression, turn off retrievable/stored
Smaller index sizeScalar or binary quantization, narrower data types, stored=false
Match embedding modelCorrect dimensions + correct metric (usually cosine)
Hybrid search balanceAdjust vector weight
Start simple: one HNSW algorithm with cosine, one profile, dimensions matching your model, retrievable=false. Add compression only when the index grows large or cost becomes an issue.

Sources

All details taken from official Microsoft Learn documentation:

Azure AI Search Vector Settings — simple guide based on Microsoft Learn. Always verify against the latest docs before production use.

No comments:

Post a Comment