Indexers - Create Or Update

Creates a new indexer or updates an indexer if it already exists.

PUT {endpoint}/indexers('{indexerName}')?api-version=2024-07-01

URI Parameters

Name In Required Type Description
endpoint
path True

string

The endpoint URL of the search service.

indexerName
path True

string

The name of the indexer to create or update.

api-version
query True

string

Client Api Version.

Request Header

Name Required Type Description
x-ms-client-request-id

string

uuid

The tracking ID sent with the request to help with debugging.

If-Match

string

Defines the If-Match condition. The operation will be performed only if the ETag on the server matches this value.

If-None-Match

string

Defines the If-None-Match condition. The operation will be performed only if the ETag on the server does not match this value.

Prefer True

string

For HTTP PUT requests, instructs the service to return the created/updated resource on success.

Request Body

Name Required Type Description
dataSourceName True

string

The name of the datasource from which this indexer reads data.

name True

string

The name of the indexer.

targetIndexName True

string

The name of the index to which this indexer writes data.

@odata.etag

string

The ETag of the indexer.

description

string

The description of the indexer.

disabled

boolean

A value indicating whether the indexer is disabled. Default is false.

encryptionKey

SearchResourceEncryptionKey

A description of an encryption key that you create in Azure Key Vault. This key is used to provide an additional level of encryption-at-rest for your indexer definition (as well as indexer execution status) when you want full assurance that no one, not even Microsoft, can decrypt them. Once you have encrypted your indexer definition, it will always remain encrypted. The search service will ignore attempts to set this property to null. You can change this property as needed if you want to rotate your encryption key; Your indexer definition (and indexer execution status) will be unaffected. Encryption with customer-managed keys is not available for free search services, and is only available for paid services created on or after January 1, 2019.

fieldMappings

FieldMapping[]

Defines mappings between fields in the data source and corresponding target fields in the index.

outputFieldMappings

FieldMapping[]

Output field mappings are applied after enrichment and immediately before indexing.

parameters

IndexingParameters

Parameters for indexer execution.

schedule

IndexingSchedule

The schedule for this indexer.

skillsetName

string

The name of the skillset executing with this indexer.

Responses

Name Type Description
200 OK

SearchIndexer

201 Created

SearchIndexer

Other Status Codes

ErrorResponse

Error response.

Examples

SearchServiceCreateOrUpdateIndexer

Sample request

PUT https://myservice.search.windows.net/indexers('myindexer')?api-version=2024-07-01


{
  "name": "myindexer",
  "description": "a cool indexer",
  "dataSourceName": "mydatasource",
  "targetIndexName": "orders",
  "schedule": {
    "interval": "PT1H",
    "startTime": "2015-01-01T00:00:00Z"
  },
  "parameters": {
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5
  },
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": null
  }
}

Sample response

{
  "name": "myindexer",
  "description": "a cool indexer",
  "dataSourceName": "mydatasource",
  "targetIndexName": "orders",
  "schedule": {
    "interval": "PT1H",
    "startTime": "2015-01-01T00:00:00Z"
  },
  "parameters": {
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5
  },
  "fieldMappings": [],
  "disabled": false,
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": null
  }
}
{
  "name": "myindexer",
  "description": "a cool indexer",
  "dataSourceName": "mydatasource",
  "targetIndexName": "orders",
  "schedule": {
    "interval": "PT1H",
    "startTime": "2015-01-01T00:00:00Z"
  },
  "parameters": {
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5
  },
  "fieldMappings": [],
  "disabled": false,
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": null
  }
}

Definitions

Name Description
AzureActiveDirectoryApplicationCredentials

Credentials of a registered application created for your search service, used for authenticated access to the encryption keys stored in Azure Key Vault.

BlobIndexerDataToExtract

Specifies the data to extract from Azure blob storage and tells the indexer which data to extract from image content when "imageAction" is set to a value other than "none". This applies to embedded image content in a .PDF or other application, or image files such as .jpg and .png, in Azure blobs.

BlobIndexerImageAction

Determines how to process embedded images and image files in Azure blob storage. Setting the "imageAction" configuration to any value other than "none" requires that a skillset also be attached to that indexer.

BlobIndexerParsingMode

Represents the parsing mode for indexing from an Azure blob data source.

BlobIndexerPDFTextRotationAlgorithm

Determines algorithm for text extraction from PDF files in Azure blob storage.

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

ErrorResponse

Error response

FieldMapping

Defines a mapping between a field in a data source and a target field in an index.

FieldMappingFunction

Represents a function that transforms a value from a data source before indexing.

IndexerExecutionEnvironment

Specifies the environment in which the indexer should execute.

IndexingParameters

Represents parameters for indexer execution.

IndexingParametersConfiguration

A dictionary of indexer-specific configuration properties. Each name is the name of a specific property. Each value must be of a primitive type.

IndexingSchedule

Represents a schedule for indexer execution.

SearchIndexer

Represents an indexer.

SearchResourceEncryptionKey

A customer-managed encryption key in Azure Key Vault. Keys that you create and manage can be used to encrypt or decrypt data-at-rest, such as indexes and synonym maps.

AzureActiveDirectoryApplicationCredentials

Credentials of a registered application created for your search service, used for authenticated access to the encryption keys stored in Azure Key Vault.

Name Type Description
applicationId

string

An AAD Application ID that was granted the required access permissions to the Azure Key Vault that is to be used when encrypting your data at rest. The Application ID should not be confused with the Object ID for your AAD Application.

applicationSecret

string

The authentication key of the specified AAD application.

BlobIndexerDataToExtract

Specifies the data to extract from Azure blob storage and tells the indexer which data to extract from image content when "imageAction" is set to a value other than "none". This applies to embedded image content in a .PDF or other application, or image files such as .jpg and .png, in Azure blobs.

Name Type Description
allMetadata

string

Extracts metadata provided by the Azure blob storage subsystem and the content-type specific metadata (for example, metadata unique to just .png files are indexed).

contentAndMetadata

string

Extracts all metadata and textual content from each blob.

storageMetadata

string

Indexes just the standard blob properties and user-specified metadata.

BlobIndexerImageAction

Determines how to process embedded images and image files in Azure blob storage. Setting the "imageAction" configuration to any value other than "none" requires that a skillset also be attached to that indexer.

Name Type Description
generateNormalizedImagePerPage

string

Extracts text from images (for example, the word "STOP" from a traffic stop sign), and embeds it into the content field, but treats PDF files differently in that each page will be rendered as an image and normalized accordingly, instead of extracting embedded images. Non-PDF file types will be treated the same as if "generateNormalizedImages" was set.

generateNormalizedImages

string

Extracts text from images (for example, the word "STOP" from a traffic stop sign), and embeds it into the content field. This action requires that "dataToExtract" is set to "contentAndMetadata". A normalized image refers to additional processing resulting in uniform image output, sized and rotated to promote consistent rendering when you include images in visual search results. This information is generated for each image when you use this option.

none

string

Ignores embedded images or image files in the data set. This is the default.

BlobIndexerParsingMode

Represents the parsing mode for indexing from an Azure blob data source.

Name Type Description
default

string

Set to default for normal file processing.

delimitedText

string

Set to delimitedText when blobs are plain CSV files.

json

string

Set to json to extract structured content from JSON files.

jsonArray

string

Set to jsonArray to extract individual elements of a JSON array as separate documents.

jsonLines

string

Set to jsonLines to extract individual JSON entities, separated by a new line, as separate documents.

text

string

Set to text to improve indexing performance on plain text files in blob storage.

BlobIndexerPDFTextRotationAlgorithm

Determines algorithm for text extraction from PDF files in Azure blob storage.

Name Type Description
detectAngles

string

May produce better and more readable text extraction from PDF files that have rotated text within them. Note that there may be a small performance speed impact when this parameter is used. This parameter only applies to PDF files, and only to PDFs with embedded text. If the rotated text appears within an embedded image in the PDF, this parameter does not apply.

none

string

Leverages normal text extraction. This is the default.

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

object

The additional info.

type

string

The additional info type.

ErrorDetail

The error detail.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.

code

string

The error code.

details

ErrorDetail[]

The error details.

message

string

The error message.

target

string

The error target.

ErrorResponse

Error response

Name Type Description
error

ErrorDetail

The error object.

FieldMapping

Defines a mapping between a field in a data source and a target field in an index.

Name Type Description
mappingFunction

FieldMappingFunction

A function to apply to each source field value before indexing.

sourceFieldName

string

The name of the field in the data source.

targetFieldName

string

The name of the target field in the index. Same as the source field name by default.

FieldMappingFunction

Represents a function that transforms a value from a data source before indexing.

Name Type Description
name

string

The name of the field mapping function.

parameters

object

A dictionary of parameter name/value pairs to pass to the function. Each value must be of a primitive type.

IndexerExecutionEnvironment

Specifies the environment in which the indexer should execute.

Name Type Description
private

string

Indicates that the indexer should run with the environment provisioned specifically for the search service. This should only be specified as the execution environment if the indexer needs to access resources securely over shared private link resources.

standard

string

Indicates that the search service can determine where the indexer should execute. This is the default environment when nothing is specified and is the recommended value.

IndexingParameters

Represents parameters for indexer execution.

Name Type Default value Description
batchSize

integer

The number of items that are read from the data source and indexed as a single batch in order to improve performance. The default depends on the data source type.

configuration

IndexingParametersConfiguration

A dictionary of indexer-specific configuration properties. Each name is the name of a specific property. Each value must be of a primitive type.

maxFailedItems

integer

0

The maximum number of items that can fail indexing for indexer execution to still be considered successful. -1 means no limit. Default is 0.

maxFailedItemsPerBatch

integer

0

The maximum number of items in a single batch that can fail indexing for the batch to still be considered successful. -1 means no limit. Default is 0.

IndexingParametersConfiguration

A dictionary of indexer-specific configuration properties. Each name is the name of a specific property. Each value must be of a primitive type.

Name Type Default value Description
allowSkillsetToReadFileData

boolean

False

If true, will create a path //document//file_data that is an object representing the original file data downloaded from your blob data source. This allows you to pass the original file data to a custom skill for processing within the enrichment pipeline, or to the Document Extraction skill.

dataToExtract

BlobIndexerDataToExtract

contentAndMetadata

Specifies the data to extract from Azure blob storage and tells the indexer which data to extract from image content when "imageAction" is set to a value other than "none". This applies to embedded image content in a .PDF or other application, or image files such as .jpg and .png, in Azure blobs.

delimitedTextDelimiter

string

For CSV blobs, specifies the end-of-line single-character delimiter for CSV files where each line starts a new document (for example, "|").

delimitedTextHeaders

string

For CSV blobs, specifies a comma-delimited list of column headers, useful for mapping source fields to destination fields in an index.

documentRoot

string

For JSON arrays, given a structured or semi-structured document, you can specify a path to the array using this property.

excludedFileNameExtensions

string

Comma-delimited list of filename extensions to ignore when processing from Azure blob storage. For example, you could exclude ".png, .mp4" to skip over those files during indexing.

executionEnvironment

IndexerExecutionEnvironment

standard

Specifies the environment in which the indexer should execute.

failOnUnprocessableDocument

boolean

False

For Azure blobs, set to false if you want to continue indexing if a document fails indexing.

failOnUnsupportedContentType

boolean

False

For Azure blobs, set to false if you want to continue indexing when an unsupported content type is encountered, and you don't know all the content types (file extensions) in advance.

firstLineContainsHeaders

boolean

True

For CSV blobs, indicates that the first (non-blank) line of each blob contains headers.

imageAction

BlobIndexerImageAction

none

Determines how to process embedded images and image files in Azure blob storage. Setting the "imageAction" configuration to any value other than "none" requires that a skillset also be attached to that indexer.

indexStorageMetadataOnlyForOversizedDocuments

boolean

False

For Azure blobs, set this property to true to still index storage metadata for blob content that is too large to process. Oversized blobs are treated as errors by default. For limits on blob size, see https://learn.microsoft.com/azure/search/search-limits-quotas-capacity.

indexedFileNameExtensions

string

Comma-delimited list of filename extensions to select when processing from Azure blob storage. For example, you could focus indexing on specific application files ".docx, .pptx, .msg" to specifically include those file types.

parsingMode

BlobIndexerParsingMode

default

Represents the parsing mode for indexing from an Azure blob data source.

pdfTextRotationAlgorithm

BlobIndexerPDFTextRotationAlgorithm

none

Determines algorithm for text extraction from PDF files in Azure blob storage.

queryTimeout

string

00:05:00

Increases the timeout beyond the 5-minute default for Azure SQL database data sources, specified in the format "hh:mm:ss".

IndexingSchedule

Represents a schedule for indexer execution.

Name Type Description
interval

string

The interval of time between indexer executions.

startTime

string

The time when an indexer should start running.

SearchIndexer

Represents an indexer.

Name Type Default value Description
@odata.etag

string

The ETag of the indexer.

dataSourceName

string

The name of the datasource from which this indexer reads data.

description

string

The description of the indexer.

disabled

boolean

False

A value indicating whether the indexer is disabled. Default is false.

encryptionKey

SearchResourceEncryptionKey

A description of an encryption key that you create in Azure Key Vault. This key is used to provide an additional level of encryption-at-rest for your indexer definition (as well as indexer execution status) when you want full assurance that no one, not even Microsoft, can decrypt them. Once you have encrypted your indexer definition, it will always remain encrypted. The search service will ignore attempts to set this property to null. You can change this property as needed if you want to rotate your encryption key; Your indexer definition (and indexer execution status) will be unaffected. Encryption with customer-managed keys is not available for free search services, and is only available for paid services created on or after January 1, 2019.

fieldMappings

FieldMapping[]

Defines mappings between fields in the data source and corresponding target fields in the index.

name

string

The name of the indexer.

outputFieldMappings

FieldMapping[]

Output field mappings are applied after enrichment and immediately before indexing.

parameters

IndexingParameters

Parameters for indexer execution.

schedule

IndexingSchedule

The schedule for this indexer.

skillsetName

string

The name of the skillset executing with this indexer.

targetIndexName

string

The name of the index to which this indexer writes data.

SearchResourceEncryptionKey

A customer-managed encryption key in Azure Key Vault. Keys that you create and manage can be used to encrypt or decrypt data-at-rest, such as indexes and synonym maps.

Name Type Description
accessCredentials

AzureActiveDirectoryApplicationCredentials

Optional Azure Active Directory credentials used for accessing your Azure Key Vault. Not required if using managed identity instead.

keyVaultKeyName

string

The name of your Azure Key Vault key to be used to encrypt your data at rest.

keyVaultKeyVersion

string

The version of your Azure Key Vault key to be used to encrypt your data at rest.

keyVaultUri

string

The URI of your Azure Key Vault, also referred to as DNS name, that contains the key to be used to encrypt your data at rest. An example URI might be https://my-keyvault-name.vault.azure.net.