Azure AI Search
Compatible with the Microsoft.Search ARM management plane as the azurerm_search_service Terraform
resource, the azure-mgmt-search SDKs and the az search service, az search admin-key and
az search query-key commands use it. Floci AZ serves search services with their admin and query API
keys. The other az search command groups are not served yet: see
Notes & limitations.
Management plane only, for now. Indexes, documents, queries, indexers and skillsets are not served yet. A data-plane request answers
404.HTTP-only: no Docker. Search services are in-process ARM state. There is no sidecar.
Features
- Search services:
Microsoft.Search/searchServicesCreateOrUpdate, Update (PATCH), Get, Delete, and List by resource group and by subscription. A service issucceededandrunningas soon as thePUTanswers; there is no provisioning delay - Admin keys:
listAdminKeysandregenerateAdminKey/{primary|secondary}. Regenerating one key leaves the other untouched - Query keys:
listQueryKeys,createQueryKey/{name}anddeleteQueryKey/{key}. A new service has one unnamed query key, as in Azure. Deleting a key answers200, a key the service does not have answers204, so a repeated delete succeeds, and a missing service answers404 - Name availability:
checkNameAvailabilityreports a taken name asAlreadyExistsand a malformed one asInvalid - Managed identity:
SystemAssigned,UserAssignedandSystemAssigned, UserAssigned. A system-assigned identity gets aprincipalIdandtenantIdthat stay stable across updates. Each user-assigned identity reads back theprincipalIdandclientIdof the managed identity it names, and one that does not exist is refused with400 FailedIdentityOperation. Ids a caller sends are read-only and are not echoed
Endpoints
PUT/GET/PATCH/DELETE .../providers/Microsoft.Search/searchServices/{name}
GET /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Search/searchServices
GET /subscriptions/{sub}/providers/Microsoft.Search/searchServices
POST /subscriptions/{sub}/providers/Microsoft.Search/checkNameAvailability
POST .../searchServices/{name}/listAdminKeys
POST .../searchServices/{name}/regenerateAdminKey/{primary|secondary}
POST .../searchServices/{name}/listQueryKeys # GET is accepted too
POST .../searchServices/{name}/createQueryKey/{keyName}
DELETE .../searchServices/{name}/deleteQueryKey/{key}
A service's properties.endpoint is https://{name}.search.windows.net (the cloud's own search
suffix under floci-az.cloud). The emulator claims that host form and the path-style
/{name}-search/ prefix for the data plane that is to come.
Quickstart
Azure CLI
az group create -n my-rg -l eastus
az search service create -n my-search -g my-rg -l eastus --sku basic
az search service show -n my-search -g my-rg --query endpoint -o tsv
az search admin-key show --service-name my-search -g my-rg
az search query-key create --service-name my-search -g my-rg -n my-app
Terraform / OpenTofu
resource "azurerm_search_service" "search" {
name = "my-search"
resource_group_name = azurerm_resource_group.rg.name
location = azurerm_resource_group.rg.location
sku = "basic"
}
output "search_primary_key" {
value = azurerm_search_service.search.primary_key
sensitive = true
}
Response shape
The shapes follow the resource-manager spec (2025-05-01) and the responses Azure gives the az
CLI:
PUTanswers201on create and200on update, with no polling headerslocationis answered as a display name (East US), while the generic resource listings carry the canonical one (eastus)provisioningStateissucceededandstatusisrunning, both lowercasetagsis{}when the client sent noneauthOptionsis{"apiKeyOnly":{}}, ornullwhendisableLocalAuthistruesemanticSearchdefaults tofree,publicNetworkAccesstoEnabled, andreplicaCountandpartitionCountto1knowledgeRetrieval(from2026-03-01-preview) appears once a client has set it, and is kept across later updates- The keys never appear on the resource: only the key operations return them
SKU limits
| SKU | Replicas | Partitions |
|---|---|---|
free |
1 | 1 |
basic |
1 to 3 | 1 to 3 |
standard, standard2, standard3 |
1 to 12 | 1, 2, 3, 4, 6 or 12 |
standard3 with hostingMode: HighDensity |
1 to 12 | 1 to 3 |
storage_optimized_l1, storage_optimized_l2 |
1 to 12 | 1, 2, 3, 4, 6 or 12 |
- Replicas times partitions is at most 36 search units
hostingMode: HighDensityis accepted onstandard3onlybasicgets the three partitions of a service created after April 2024. Older Azure services are limited to one- Not enforced: regional availability, subscription quota (such as one
freeservice per subscription), which SKUs offer semantic search, and Azure's restrictions on changing the SKU of an existing service
The limits come from the 2025-05-01 spec and Microsoft's
service limits page.
Configuration
| Env var | Default | Description |
|---|---|---|
FLOCI_AZ_SERVICES_SEARCH_ENABLED |
true |
Enable/disable the service |
Notes & limitations
- No data plane yet. There are no indexes, documents, queries, indexers, data sources or skillsets. The keys are real values that stay stable, but nothing validates them yet.
- Service names are global. A name is a DNS label under the search suffix, so a second service of
the same name is refused with
409 Conflictin any subscription or resource group. Azure's own code for that conflict is not publicly documented. - Validation. A create without a
sku, an unknown SKU name, and areplicaCountorpartitionCountoutside 1 to 12 are refused with400 InvalidRequestContent. So is a scale the SKU does not reach (see SKU limits). APATCHis judged on the service as it would leave it, so changing only the SKU of a service that is too large for the new one is refused too. Azure's own error code for these is not publicly documented. - Field types. A field sent with the wrong JSON type, such as
disableLocalAuth: "true",dataExfiltrationProtections: "BlockAll"ornetworkRuleSet.ipRules: "invalid", is refused with400 InvalidRequestContentrather than replaced by its default, and so is an identitytypeoutside the spec's four. Anullis no value and keeps what is stored. - Enums and firewall rules.
hostingMode,computeType,publicNetworkAccess,semanticSearch,knowledgeRetrieval,networkRuleSet.bypass,encryptionWithCmk.enforcementanddataExfiltrationProtectionsmust hold a value the spec lists, in any casing, and each firewall rule must be an IPv4 address or CIDR range. Anything else is refused with400 InvalidRequestContent. The allowed values are the union over every api-version, since every api-version is served the same way. - Local authentication. A request that sends
disableLocalAuth: truetogether withauthOptionsis refused with400 InvalidRequestContent, as the spec rules out that combination. A service with local authentication disabled answersauthOptions: null. - Semantic ranker. A service created without
semanticSearchreportsfree, the spec's default and what Azure answers. This is reported on every SKU, includingfree, which Azure may treat differently: no public recording shows afree-SKU service. - Fixed at creation. A
PUTthat moves an existing service to another location is refused with ARM's400 InvalidResourceLocation. APUTorPATCHthat sends a differenthostingModeis refused with400 InvalidRequestContent, and aPUTthat leaves it out keeps the stored one. - Naming rule. With
strict-names, a name must be 2 to 60 lowercase letters, digits and hyphens, start with two letters or digits, not end with a hyphen and have no consecutive hyphens. -
Not modelled. These answer
404 ResourceNotFound:- private endpoint connections, shared private link resources and private link resources
(
az search private-endpoint-connection,shared-private-link-resource,private-link-resource) - network security perimeter configurations
- usage and quota (
az search usage list,locations/{location}/usages) - regional offerings (
az search offering list) and service upgrade (az search service upgrade) - the provider's operation list,
GET /providers/Microsoft.Search/operations
The
privateEndpointConnectionsandsharedPrivateLinkResourcesproperties of a service are always empty lists.autoGeneratedDomainNameLabelScope(2026-09-01-preview) is not modelled either: it would change the service's hostname, so it is dropped rather than echoed. - Storage. Services and their keys are kept in thesearchstorage backend, so they followfloci-az.storage.services.search.mode(the globalstorage.modeby default). - private endpoint connections, shared private link resources and private link resources
(