Retrieve Cache Data with Tags

Note

This feature is only available in NCache Enterprise Edition.

Once the data is tagged with one or multiple tags, the data can be retrieved using these tags. Data can be retrieved by a specified tag or one or all tags.

Pre-Requisites

  • Include the following namespace in your application:
    • Alachisoft.NCache.Client
    • Alachisoft.NCache.Runtime.Caching
    • Alachisoft.NCache.Runtime.Exceptions
  • The application must be connected to cache before performing the operation.
  • Cache must be running.
  • Make sure that the data being added is serializable.
  • To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Retrieve Keys Associated with a Tag

Keys can be retrieved from the cache by tags either by GetKeysByTag, GetKeysByAnyTag or GetKeysByAllTags. All these methods are explained below.

GetKeysByTag

GetKeysByTag(../dotnet-api-ref/Alachisoft.NCache.Client.Services.ISearchService.GetKeysByTag.html) is a method which retrieves the keys by one specified tag. The specified tag is the search criteria for the data in the cache. For Java, the method used for retrieving keys by tag is getKeysByTag.

Following example retrieves the keys of the items associated with the specified tag from the cache.

Warning

Providing Null tag array will throw an ArgumentNullException.

try
{
    // Following tags are created and item is added in the cache with these tags
    Tag[] tags = new Tag[2];
    tags[0] = new Tag("Important Customers");
    tags[1] = new Tag("East Coast Customers");

    // Keys with the Tag 'Important Customers' are retrieved
    // Retrieved Cache keys are then stored in an ICollection
    ICollection<string> retrievedKeys = cache.SearchService.GetKeysByTag(tags[0]);

    if (retrievedKeys != null && retrievedKeys.Count > 0)
    {
        // Iterate over key result
        foreach (var key in retrievedKeys)
        {
            // Perform operations            
        }
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures 
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

GetKeysByTag with Wildcard expressions

NCache also provides support for retrieving keys from the cache using tags with wildcard expressions. The special characters supported in wild search by NCache are:

  • *: Used as a substitute for zero or more characters in the string.

  • ?: Used as a substitute for a single character in the string.

The following example retrieves the keys of the items associated with tags along with wild card expressions.

try
{
    // Pre-condition: Cache is already connected

    // Following tags are created and items are added in the cache with these tags
    Tag[] tags = new Tag[3];
    tags[0] = new Tag("Important Customers");
    tags[1] = new Tag("East Coast Customers");
    tags[2] = new Tag("West Coast Customers");

    // Retrieves all the keys associated with customers
    // containing any prefix before customer
    // i.e 'Important Customers' as well as 'East Coast Customers' and 'West Coast Customers'
    ICollection<string> retrieveKeys = cache.SearchService.GetKeysByTag("*Customers");

    if (retrieveKeys != null && retrieveKeys.Count > 0)
    {
        // Iterate over key result
        foreach (var key in retrieveKeys)
        {
            // Perform operations                      
        }
    }

    // Retrieves all the keys associated with the tags
    // 'East Coast Customers' and 'West Coast Customers'
    ICollection<string> retrieveCoastCustomersKeys = search.GetKeysByTag("??st Customers");

    if (retrieveCoastCustomersKeys != null && retrieveCoastCustomersKeys.Count > 0)
    {
        // Perform operations as done for 'Customers'
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures 
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

GetKeysByAnyTag

GetKeysByTag(../dotnet-api-ref/Alachisoft.NCache.Client.Services.ISearchService.GetKeysByTag.html) is a method with the search option as ByAnyTag where multiple tags are provided and the key(s) matching ANY of the provided tags will be retrieved. In case of Java, getKeysByAnyTag is used to retrieve keys matching any of the tags provided.

Following example retrieves the keys which matches ANY of the tag provided in the list tags.

Warning

Providing Null tag list will throw an ArgumentNullException.

try
{
    // Following tags are created and item is added in the cache with these tags

    Tag[] tags = new Tag[2];
    tags[0] = new Tag("Important Customers");
    tags[1] = new Tag("East Coast Customers");

    // Keys associated with any of the Tag in the list 'tags' are retrieved
    // Retrieved Cache keys are then stored in an ICollection
    ICollection<string> keys = cache.SearchService.GetKeysByTags(tags, TagSearchOptions.ByAnyTag);

    // Check if any keys are failed to retrieve
    if (keys != null && keys.Count > 0)
    {
        // Iterate over key result
        foreach (var key in keys)
        {
            // Perform operations
        }
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures 
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

GetKeysByAllTags

GetKeysByTag(../dotnet-api-ref/Alachisoft.NCache.Client.Services.ISearchService.GetKeysByTag.html) is a method with the search option as ByAllTags where multiple tags are provided and key(s) matching ALL of the provided tags will be retrieved. For Java, getKeysbyAllTags is used to search for items matching all the tags provided.

The following example retrieves the keys of items in the cache containing ALL the tags in the list tags.

Warning

Providing Null tag list will throw an ArgumentNullException.

try
{
    // Pre-condition: Cache is already connected

    // Following tags are created and item is added in the cache with these tags
    Tag[] tags = new Tag[2];
    tags[0] = new Tag("Important Customers");
    tags[1] = new Tag("East Coast Customers");

    // Keys associated with all of the Tags in the list 'tags' are retrieved
    // Retrieved Cache keys are then stored in an ICollection
    ICollection<string> keys = cache.SearchService.GetKeysByTags(tags, TagSearchOptions.ByAllTags);

    // Check if any keys are failed to retrieve
    if (keys != null && keys.Count > 0)
    {
        // Iterate over key result
        foreach (var key in keys)
        {
            // Perform operations 
        }
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures 
    // Operation Timeout
    // Operation performed during state transfer
}   
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Retrieve Cached Data from Cache Containing Tag

Similar to keys, cached items (keys and values) can also be retrieved from the cache either by GetByTag, GetByAnyTag or GetByAllTags. All these methods are explained below.

GetByTag

GetByTag is a method in which a single tag is provided and all the ""keys and values"" associated with that tag are retrieved. In java section of the code, the method used for this purpose is getByTag.

Following example retrieves the keys and values against these keys, associated with the tag Important Customers.

Warning

Providing Null tag array will throw an ArgumentNullException.

try
{
    // Pre-condition: Cache is already connected

    // Following tags are created and item is added in the cache with these tags
    Tag[] tags = new Tag[2];
    tags[0] = new Tag("Important Customers");
    tags[1] = new Tag("East Coast Customers");

    // Keys and values with the Tag 'Important Customers' and 'East Coast Customers' are retrieved 
    IDictionary<string, Customer> retrievedDictionary = cache.SearchService.GetByTags<Customer>(tags, TagSearchOptions.ByAllTags);

    if (retrievedDictionary != null)
    {
        foreach (KeyValuePair<string, Customer> kvp in retrievedDictionary)
        {
            //perform operations
        }
    }
    else
    {
        // Object not of Customer type
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures 
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

GetByTag with Wildcard expressions

NCache also provides support for retrieving keys from the cache using tags with wildcard expressions. The special characters supported in wild search by NCache are:

  • *: Used as a substitute for zero or more characters in the string.

  • ?: Used as a substitute for a single character in the string.

The following example retrieves the data of the items associated with tags along with wild card expressions.

try
{
   // Pre-condition: Cache is already connected

    // Following tags are created and items are added in the cache with these tags
    Tag[] tags = new Tag[3];
    tags[0] = new Tag("Important Customers");
    tags[1] = new Tag("East Coast Customers");
    tags[2] = new Tag("West Coast Customers");

    // Retrieves all the data associated with customers
    // containing any prefix before customer
    // i.e 'Important Customers' as well as 'East Coast Customers' and 'West Coast Customers'
    IDictionary<string, Customer> retrievedDictionary = cache.SearchService.GetByTag<Customer>("*Customers");

    if (retrievedDictionary != null)
    {
        foreach (KeyValuePair<string, Customer> kvp in retrievedDictionary)
        {
            //perform operations
        }
    }
    else
    {
        // Object not of Customer type
    }

    // Retrieves all the data associated with the tags
    // 'East Coast Customers' and 'West Coast Customers'
    IDictionary<string, Customer> retrievedDictionaryEW = search.GetByTag<Customer>("??st Customers");
    if (retrievedDictionary != null)
    {
        foreach (KeyValuePair<string, Customer> kvp in retrievedDictionary)
        {
            //perform similar operations as done for "customers"
        }
    }
    else
    {
        // Object not of Customer type
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures 
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

GetByAnyTag

GetByTag is a method and ByAnyTag is the search option in which a list of tags is provided and all the ""keys and values"" associated with ANY of the tags in the tag list are retrieved. For Java, getByAnyTag is used for retrieving keys and their values matching any of the tags provided.

Following example retrieves the keys and values against these keys, associated with any of the tags in the list tags.

Warning

Providing Null tag list will throw an ArgumentNullException.

try
{
    // Following tags are created and item is added in  the cache with these tags
    Tag[] tags = new Tag[2];
    tags[0] = new Tag("Important Customers");
    tags[1] = new Tag("East Coast Customers");

    // Keys and values with any of the Tags in the tags list are retrieved
    IDictionary<string, Customer> retrievedDictionary = cache.SearchService.GetByTags<Customer>(tags, TagSearchOptions.ByAnyTag);

    if (retrievedDictionary != null)
    {
        foreach (KeyValuePair<string, Customer> kvp in retrievedDictionary)
        {
        //perform operations
        }
    }
    else
    {
        // Object not of Customer type
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures 
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

GetByAllTags

GetByTag is a method and ByAllTags is the search option in which a list of tags is provided and all the ""keys and values"" associated with ALL of the tags in the tag list are retrieved. getByAllTags is used to get they keys and values matching all the tags in case of Java.

Following example retrieves the keys and values against these keys, associated with all of the tags in the list tags.

Warning

Providing Null tag list will throw an ArgumentNullException.

try
{
    // Pre-condition: Cache is already connected

    // Following tags are created and item is added in the cache with these tags
    Tag[] tags = new Tag[2];
    tags[0] = new Tag("Important Customers");
    tags[1] = new Tag("East Coast Customers");

    // Keys and values with all of the Tags in the tags list are retrieved
    IDictionary<string, Customer> retrievedDictionary = cache.SearchService.GetByTags<Customer>(tags, TagSearchOptions.ByAllTags);

    if (retrievedDictionary != null)
    {
        foreach (KeyValuePair<string, Customer> kvp in retrievedDictionary)
        {
            // Perform operations
        }
    }
    else
    {
        // Object not of Customer type
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures 
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Additional Resources

NCache provides sample application for Tags at:

  • GitHub
  • Shipped with NCache: %NCHOME%\samples\dotnet\GroupsAndTags

See Also

Use Groups for Logical Data Grouping
Add/Update Cache Data with Tags
Remove Cache Data with Tags
Search Tag Data in Cache with SQL
Delete Tag Data from Cache with SQL
Named Tags with Cache Data