Use blob index tags to manage and find data with JavaScript

  • 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.

To set tags at blob upload time, create a BlobClient then use the following method:

The following example performs this task.

// A blob can have up to 10 tags. 
//
// const tags = {
//   project: 'End of month billing summary',
//   reportOwner: 'John Doe',
//   reportPresented: 'April 2022'
// }
async function setTags(containerClient, blobName, tags) {

  // Create blob client from container client
  const blockBlobClient = await containerClient.getBlockBlobClient(blobName);

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

  console.log(`uploading blob ${blobName}`);
}

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

Related articles
Manage and find Azure Blob data with blob index tags
Set Blob Tags (REST API)

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.

To get tags, create a BlobClient then use the following method:

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

async function getTags(containerClient, blobName) {

  // Create blob client from container client
  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.

To find blobs, create a BlobClient then use 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.

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:

Code samples

Client library resources

See also