Use blob index tags to manage and find data with JavaScript or TypeScript

  • Article

This article shows how to use blob index tags to manage and find data using the Azure Storage client library for JavaScript.

Prerequisites

About blob index tags

Blob index tags categorize data in your storage account using key-value tag attributes. These tags are automatically indexed and exposed as a searchable multi-dimensional index to easily find data. This article shows you how to set, get, and find data using blob index tags.

Blob index tags aren't supported for storage accounts with hierarchical namespace enabled. To learn more about the blob index tag feature along with known issues and limitations, see Manage and find Azure Blob data with blob index tags.

Set tags

You can set index tags if your code has authorized access to blob data through one of the following mechanisms:

For more information, see Setting blob index tags.

You can set tags by using the following method:

The specified tags in this method replace existing tags. If old values must be preserved, they must be downloaded and included in the call to this method. The following example shows how to set tags:

async function setBlobTags(containerClient, blobName) {
  const blockBlobClient = await containerClient.getBlockBlobClient(blobName);

  const tags = {
    'Sealed': 'false',
    'Content': 'image',
    'Date': '2022-07-18',
  }

  // Set tags
  await blockBlobClient.setTags(tags);
}

You can delete all tags by passing an empty JSON object into the setTags method.

Get tags

You can get index tags if your code has authorized access to blob data through one of the following mechanisms:

For more information, see Getting and listing blob index tags.

You can get tags by using the following method:

The following example shows how to retrieve and iterate over the blob's tags.

async function getBlobTags(containerClient, blobName) {
  const blockBlobClient = await containerClient.getBlockBlobClient(blobName);

  // Get tags
  const result = await blockBlobClient.getTags();

  for (const tag in result.tags) {

      console.log(`TAG: ${tag}: ${result.tags[tag]}`);
  }
}

Filter and find data with blob index tags

You can use index tags to find and filter data if your code has authorized access to blob data through one of the following mechanisms:

For more information, see Finding data using blob index tags.

Note

You can't use index tags to retrieve previous versions. Tags for previous versions aren't passed to the blob index engine. For more information, see Conditions and known issues.

Data is queried with a JSON object sent as a string. The properties don't need to have additional string quotes but the values do need additional string quotes.

The following table shows some query strings:

Query string for tags (tagOdataQuery) Description
id='1' AND project='billing' Filter blobs across all containers based on these two properties
owner='PhillyProject' AND createdOn >= '2021-12' AND createdOn <= '2022-06' Filter blobs across all containers based on strict property value for owner and range of dates for createdOn property.
@container = 'my-container' AND createdBy = 'Jill' Filter by container and specific property. In this query, createdBy is a text match and doesn't indicate an authorization match through Active Directory.

You can find data by using the following method:

The following example finds all blobs matching the tagOdataQuery parameter.

async function findBlobsByQuery(blobServiceClient, tagOdataQuery) {

  // page size
  const maxPageSize = 10;

  let i = 1;
  let marker;

  const listOptions = {
    includeMetadata: true,
    includeSnapshots: false,
    includeTags: true,
    includeVersions: false
  };

  let iterator = blobServiceClient.findBlobsByTags(tagOdataQuery, listOptions).byPage({ maxPageSize });
  let response = (await iterator.next()).value;

  // Prints blob names
  if (response.blobs) {
    for (const blob of response.blobs) {
      console.log(`Blob ${i++}: ${blob.name} - ${JSON.stringify(blob.tags)}`);
    }
  }

  // Gets next marker
  marker = response.continuationToken;
  
  // no more blobs
  if (!marker) return;
  
  // Passing next marker as continuationToken
  iterator = blobServiceClient
    .findBlobsByTags(tagOdataQuery, listOptions)
    .byPage({ continuationToken: marker, maxPageSize });
  response = (await iterator.next()).value;

  // Prints blob names
  if (response.blobs) {
    for (const blob of response.blobs) {
      console.log(`Blob ${i++}: ${blob.name} - ${JSON.stringify(blob.tags)}`);
    }
  }
}

And example output for this function shows the matched blobs and their tags, based on the console.log code in the preceding function:

Response
Blob 1: set-tags-1650565920363-query-by-tag-blob-a-1.txt - {"createdOn":"2022-01","owner":"PhillyProject","project":"set-tags-1650565920363"}

Resources

To learn more about how to use index tags to manage and find data using the Azure Blob Storage client library for JavaScript, see the following resources.

Code samples

REST API operations

The Azure SDK for JavaScript contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar JavaScript paradigms. The client library methods for managing and using blob index tags use the following REST API operations:

Client library resources

See also