TableQuery<T> Class

  • Reference
Package:
com.microsoft.azure.storage.table
  • java.lang.Object
    • com.microsoft.azure.storage.table.TableQuery<T>

Type Parameters

T

A class type which implements TableEntity and contains a nullary constructor. Note: when using an inner class to define the class type, mark the class as static.

public class TableQuery

A class which represents a query against a specified table. A TableQuery<T> instance aggregates the query parameters to use when the query is executed. One of the or methods of CloudTableClient must be called to execute the query. The parameters are encoded and passed to the server when the table query is executed.

To create a table query with fluent syntax, the from(final Class<T> clazzType) static factory method and the where(final String filter), select(final String[] columns), and take(final Integer take) mutator methods each return a reference to the object which can be chained into a single expression. Use the from(Class) static class factory method to create a instance that executes on the named table with entities of the specified TableEntity implementing type. Use the where(final String filter) method to specify a filter expression for the entities returned. Use the select(final String[] columns) method to specify the table entity properties to return. Use the take(final Integer take) method to limit the number of entities returned by the query. Note that nothing prevents calling these methods more than once on a , so the values saved in the will be the last encountered in order of execution.

As an example, you could construct a table query using fluent syntax:

This example creates a query on the "Products" table for all entities where the PartitionKey value is "ProductsMNO" and the RowKey value is greater than or equal to "Napkin" and requests the first 25 matching entities, selecting only the common properties and the property named "InventoryCount", and returns them as DynamicTableEntity objects.

Filter expressions for use with the where(final String filter) method or setFilterString(final String filterString) method can be created using fluent syntax with the overloaded generateFilterCondition(String propertyName, String operation, final boolean value) methods and combineFilters(String filterA, String operator, String filterB) method, using the comparison operators defined in QueryComparisons and the logical operators defined in Operators. Note that the first operand in a filter comparison must be a property name, and the second operand must evaluate to a constant. The PartitionKey and RowKey property values are types for comparison purposes.

The values that may be used in table queries are explained in more detail in the MSDN topic Querying Tables and Entities, but note that the space characters within values do not need to be URL-encoded, as this will be done when the query is executed.

The TableQuery#TableQuery(Class) constructor and TableQuery#from(Class) static factory methods require a class type which implements TableEntity and contains a nullary constructor. If the query will be executed using an EntityResolver<T>, the caller may specify TableServiceEntity as the class type.

Constructor Summary

Constructor Description
TableQuery()

Initializes an empty TableQuery<T> instance. This table query cannot be executed without setting a table entity type.

TableQuery(final Class<T> clazzType)

Initializes a TableQuery<T> with the specified table entity type. Callers may specify TableServiceEntity as the class type parameter if no more specialized type is required.

Method Summary

Modifier and Type Method and Description
String combineFilters(String filterA, String operator, String filterB)

Creates a filter condition using the specified logical operator on two filter conditions.
static<T extends TableEntity> TableQuery<T> from(final Class<T> clazzType)

A static factory method that constructs a TableQuery<T> instance and defines its table entity type. The method returns the TableQuery<T> instance reference, allowing additional methods to be chained to modify the query.

The created TableQuery<T> instance is specialized for table entities of the specified class type T. Callers may specify TableServiceEntity as the class type parameter if no more specialized type is required.
String generateFilterCondition(String propertyName, String operation, final boolean value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a boolean, as in the following example:

This statement sets to the following value:

String generateFilterCondition(String propertyName, String operation, final byte[] value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a binary value, as in the following example:

This statement sets to the following value:

String generateFilterCondition(String propertyName, String operation, final Byte[] value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a binary value, as in the following example:

This statement sets to the following value:

String generateFilterCondition(String propertyName, String operation, final Date value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a datetime value, as in the following example:

This statement sets to something like the following value:

String generateFilterCondition(String propertyName, String operation, final double value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a double value, as in the following example:

This statement sets to the following value:

String generateFilterCondition(String propertyName, String operation, final int value)

Generates a property filter condition string for an value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a numeric value, as in the following example:

This statement sets to the following value:

String generateFilterCondition(String propertyName, String operation, final long value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a numeric value, as in the following example:

This statement sets to the following value:

String generateFilterCondition(String propertyName, String operation, final String value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a string value, as in the following example:

This statement sets to the following value:

String generateFilterCondition(String propertyName, String operation, final UUID value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a UUID value, as in the following example:

This statement sets to the following value:

String generateFilterCondition(String propertyName, String operation, String value, EdmType edmType)

Generates a property filter condition string. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as the specified EdmType.
UriQueryBuilder generateQueryBuilder()

Reserved for internal use. Creates a UriQueryBuilder object representing the table query.
Class<T> getClazzType()

Gets the class type of the table entities returned by the query.
String [] getColumns()

Gets an array of the table entity property names specified in the table query. All properties in the table are returned by default if no property names are specified with a select clause in the table query. The table entity properties to return may be specified with a call to the setColumns(final String[] columns) or select(final String[] columns) methods with a array of property names as parameter.

Note that the system properties , , and are automatically requested from the table service whether specified in the TableQuery<T> or not.
String getFilterString()

Gets the filter expression specified in the table query. All entities in the table are returned by default if no filter expression is specified in the table query. A filter for the entities to return may be specified with a call to the setFilterString(final String filterString) or where(final String filter) methods.
String getSourceTableName()

Gets the name of the source table specified in the table query.
Integer getTakeCount()

Gets the number of entities the query returns specified in the table query. If this value is not specified in a table query, a maximum of 1,000 entries will be returned. The number of entities to return may be specified with a call to the setTakeCount(final Integer takeCount) or take(final Integer take) methods.

If the value returned by is greater than 1,000, the query will throw a StorageException when executed.
TableQuery<T> select(final String[] columns)

Defines the property names of the table entity properties to return when the table query is executed. The clause is optional on a table query, used to limit the table properties returned from the server. By default, a query will return all properties from the table entity.

Note that the system properties , , and are automatically requested from the table service whether specified in the TableQuery<T> or not.
void setClazzType(final Class<T> clazzType)

Sets the class type of the table entities returned by the query. A class type is required to execute a table query.

Callers may specify TableServiceEntity as the class type parameter if no more specialized type is required.
void setColumns(final String[] columns)

Sets the property names of the table entity properties to return when the table query is executed. By default, a query will return all properties from the table entity.

Note that the system properties , , and are automatically requested from the table service whether specified in the TableQuery<T> or not.
void setFilterString(final String filterString)

Sets the filter expression to use in the table query. A filter expression is optional; by default a table query will return all entities in the table.

Filter expressions for use with the setFilterString(final String filterString) method can be created using fluent syntax with the overloaded generateFilterCondition(String propertyName, String operation, final boolean value) methods and combineFilters(String filterA, String operator, String filterB) method, using the comparison operators defined in QueryComparisons and the logical operators defined in Operators. Note that the first operand in a filter comparison must be a property name, and the second operand must evaluate to a constant. The PartitionKey and RowKey property values are types for comparison purposes. For example, to query all entities with a PartitionKey value of "AccessLogs" on table query :

The values that may be used in table queries are explained in more detail in the MSDN topic

Querying Tables and Entities, but note that the space characters within values do not need to be URL-encoded, as this will be done when the query is executed.

Note that no more than 15 discrete comparisons are permitted within a filter string.
void setSourceTableName(final String sourceTableName)

Sets the name of the source table for the table query. A table query must have a source table to be executed.
void setTakeCount(final Integer takeCount)

Sets the upper bound for the number of entities the query returns. If this value is not specified in a table query, by default a maximum of 1,000 entries will be returned.

If the value specified for the parameter is greater than 1,000, the query will throw a StorageException when executed.
TableQuery<T> take(final Integer take)

Defines the upper bound for the number of entities the query returns. If this value is not specified in a table query, by default a maximum of 1,000 entries will be returned.

If the value specified for the parameter is greater than 1,000, the query will throw a StorageException when executed.
TableQuery<T> where(final String filter)

Defines a filter expression for the table query. Only entities that satisfy the specified filter expression will be returned by the query. Setting a filter expression is optional; by default, all entities in the table are returned if no filter expression is specified in the table query.

Filter expressions for use with the where(final String filter) method can be created using fluent syntax with the overloaded generateFilterCondition(String propertyName, String operation, final boolean value) methods and combineFilters(String filterA, String operator, String filterB) method, using the comparison operators defined in QueryComparisons and the logical operators defined in Operators. Note that the first operand in a filter comparison must be a property name, and the second operand must evaluate to a constant. The PartitionKey and RowKey property values are types for comparison purposes. For example, to query all entities with a PartitionKey value of "AccessLogs" on table query :

The values that may be used in table queries are explained in more detail in the MSDN topic

Querying Tables and Entities, but note that the space characters within values do not need to be URL-encoded, as this will be done when the query is executed.

Note that no more than 15 discrete comparisons are permitted within a filter string.

Constructor Details

TableQuery

public TableQuery()

Initializes an empty TableQuery<T> instance. This table query cannot be executed without setting a table entity type.

TableQuery

public TableQuery(final Class clazzType)

Initializes a TableQuery<T> with the specified table entity type. Callers may specify TableServiceEntity as the class type parameter if no more specialized type is required.

Parameters:

clazzType - The java.lang.Class of the class T that represents the table entity type for the query. Class T must be a type that implements TableEntity and has a nullary constructor.

Method Details

combineFilters

public static String combineFilters(String filterA, String operator, String filterB)

Creates a filter condition using the specified logical operator on two filter conditions.

Parameters:

filterA - A String which specifies the first formatted filter condition.
operator - A String which specifies Operators.AND or Operators.OR.
filterB - A String which specifies the first formatted filter condition.

Returns:

A String which represents the combined filter expression.

from

public static static TableQuery from(final Class clazzType)

A static factory method that constructs a TableQuery<T> instance and defines its table entity type. The method returns the TableQuery<T> instance reference, allowing additional methods to be chained to modify the query.

The created TableQuery<T> instance is specialized for table entities of the specified class type T. Callers may specify TableServiceEntity as the class type parameter if no more specialized type is required.

Parameters:

clazzType - The java.lang.Class of the class T implementing the TableEntity interface that represents the table entity type for the query.

Returns:

The TableQuery<T> instance with the entity type specialization set.

generateFilterCondition

public static String generateFilterCondition(String propertyName, String operation, final boolean value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a boolean, as in the following example:

This statement sets to the following value:

Parameters:

propertyName - A String which specifies the name of the property to compare.
operation - A String which specifies the comparison operator to use.
value - A boolean which specifies the value to compare with the property.

Returns:

A String which represents the formatted filter condition.

generateFilterCondition

public static String generateFilterCondition(String propertyName, String operation, final byte[] value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a binary value, as in the following example:

This statement sets to the following value:

Parameters:

propertyName - A String which specifies the name of the property to compare.
operation - A String which specifies the comparison operator to use.
value - A byte array which specifies the value to compare with the property.

Returns:

A String which represents the formatted filter condition.

generateFilterCondition

public static String generateFilterCondition(String propertyName, String operation, final Byte[] value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a binary value, as in the following example:

This statement sets to the following value:

Parameters:

propertyName - A String which specifies the name of the property to compare.
operation - A String which specifies the comparison operator to use.
value - A Byte array which specifies the value to compare with the property.

Returns:

A String which represents the formatted filter condition.

generateFilterCondition

public static String generateFilterCondition(String propertyName, String operation, final Date value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a datetime value, as in the following example:

This statement sets to something like the following value:

Parameters:

propertyName - A String which specifies the name of the property to compare.
operation - A String which specifies the comparison operator to use.
value - A java.util.Date which specifies the value to compare with the property.

Returns:

A String which represents the formatted filter condition.

generateFilterCondition

public static String generateFilterCondition(String propertyName, String operation, final double value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a double value, as in the following example:

This statement sets to the following value:

Parameters:

propertyName - A String which specifies the name of the property to compare.
operation - A String which specifies the comparison operator to use.
value - A double which specifies the value to compare with the property.

Returns:

A String which represents the formatted filter condition.

generateFilterCondition

public static String generateFilterCondition(String propertyName, String operation, final int value)

Generates a property filter condition string for an value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a numeric value, as in the following example:

This statement sets to the following value:

Parameters:

propertyName - A String which specifies the name of the property to compare.
operation - A String which specifies the comparison operator to use.
value - An int which specifies the value to compare with the property.

Returns:

A String which represents the formatted filter condition.

generateFilterCondition

public static String generateFilterCondition(String propertyName, String operation, final long value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a numeric value, as in the following example:

This statement sets to the following value:

Parameters:

propertyName - A String which specifies the name of the property to compare.
operation - A String which specifies the comparison operator to use.
value - A long which specifies the value to compare with the property.

Returns:

A String which represents the formatted filter condition.

generateFilterCondition

public static String generateFilterCondition(String propertyName, String operation, final String value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a string value, as in the following example:

This statement sets to the following value:

Parameters:

propertyName - A String which specifies the name of the property to compare.
operation - A String which specifies the comparison operator to use.
value - A String which specifies the value to compare with the property.

Returns:

A String which represents the formatted filter condition.

generateFilterCondition

public static String generateFilterCondition(String propertyName, String operation, final UUID value)

Generates a property filter condition string for a value. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as a UUID value, as in the following example:

This statement sets to the following value:

Parameters:

propertyName - A String which specifies the name of the property to compare.
operation - A String which specifies the comparison operator to use.
value - A UUID which specifies the value to compare with the property.

Returns:

A String which represents the formatted filter condition.

generateFilterCondition

public static String generateFilterCondition(String propertyName, String operation, String value, EdmType edmType)

Generates a property filter condition string. Creates a formatted string to use in a filter expression that uses the specified operation to compare the property with the value, formatted as the specified EdmType.

Parameters:

propertyName - A String which specifies the name of the property to compare.
operation - A String which specifies the comparison operator to use.
value - A String which specifies the value to compare with the property.
edmType - The EdmType to format the value as.

Returns:

A String which represents the formatted filter condition.

generateQueryBuilder

protected UriQueryBuilder generateQueryBuilder()

Reserved for internal use. Creates a UriQueryBuilder object representing the table query.

Returns:

A UriQueryBuilder object representing the table query.

Throws:

StorageException - if an error occurs in adding or encoding the query parameters.

getClazzType

public Class getClazzType()

Gets the class type of the table entities returned by the query.

Returns:

The java.lang.Class of the class T that represents the table entity type for the query.

getColumns

public String [] getColumns()

Gets an array of the table entity property names specified in the table query. All properties in the table are returned by default if no property names are specified with a select clause in the table query. The table entity properties to return may be specified with a call to the setColumns(final String[] columns) or select(final String[] columns) methods with a array of property names as parameter.

Note that the system properties , , and are automatically requested from the table service whether specified in the TableQuery<T> or not.

Returns:

An array of String objects which represents the property names of the table entity properties to return in the query.

getFilterString

public String getFilterString()

Gets the filter expression specified in the table query. All entities in the table are returned by default if no filter expression is specified in the table query. A filter for the entities to return may be specified with a call to the setFilterString(final String filterString) or where(final String filter) methods.

Returns:

A String which represents the filter expression used in the query.

getSourceTableName

protected String getSourceTableName()

Gets the name of the source table specified in the table query.

Returns:

A String which represents the name of the source table used in the query.

getTakeCount

public Integer getTakeCount()

Gets the number of entities the query returns specified in the table query. If this value is not specified in a table query, a maximum of 1,000 entries will be returned. The number of entities to return may be specified with a call to the setTakeCount(final Integer takeCount) or take(final Integer take) methods.

If the value returned by is greater than 1,000, the query will throw a StorageException when executed.

Returns:

An Integer which represents the maximum number of entities for the table query to return.

select

public TableQuery select(final String[] columns)

Defines the property names of the table entity properties to return when the table query is executed. The clause is optional on a table query, used to limit the table properties returned from the server. By default, a query will return all properties from the table entity.

Note that the system properties , , and are automatically requested from the table service whether specified in the TableQuery<T> or not.

Parameters:

columns - An array of String objects which specify the property names of the table entity properties to return when the query is executed.

Returns:

A reference to the TableQuery<T> instance with the table entity properties to return set.

setClazzType

public void setClazzType(final Class clazzType)

Sets the class type of the table entities returned by the query. A class type is required to execute a table query.

Callers may specify TableServiceEntity as the class type parameter if no more specialized type is required.

Parameters:

clazzType - The java.lang.Class of the class T that represents the table entity type for the query. Class T must be a type that implements TableEntity and has a nullary constructor,

setColumns

public void setColumns(final String[] columns)

Sets the property names of the table entity properties to return when the table query is executed. By default, a query will return all properties from the table entity.

Note that the system properties , , and are automatically requested from the table service whether specified in the TableQuery<T> or not.

Parameters:

columns - An array of String objects which specify the property names of the table entity properties to return when the query is executed.

setFilterString

public void setFilterString(final String filterString)

Sets the filter expression to use in the table query. A filter expression is optional; by default a table query will return all entities in the table.

Filter expressions for use with the setFilterString(final String filterString) method can be created using fluent syntax with the overloaded generateFilterCondition(String propertyName, String operation, final boolean value) methods and combineFilters(String filterA, String operator, String filterB) method, using the comparison operators defined in QueryComparisons and the logical operators defined in Operators. Note that the first operand in a filter comparison must be a property name, and the second operand must evaluate to a constant. The PartitionKey and RowKey property values are types for comparison purposes. For example, to query all entities with a PartitionKey value of "AccessLogs" on table query :

The values that may be used in table queries are explained in more detail in the MSDN topic

Querying Tables and Entities, but note that the space characters within values do not need to be URL-encoded, as this will be done when the query is executed.

Note that no more than 15 discrete comparisons are permitted within a filter string.

Parameters:

filterString - A String which represents the filter expression to use in the query.

setSourceTableName

protected void setSourceTableName(final String sourceTableName)

Sets the name of the source table for the table query. A table query must have a source table to be executed.

Parameters:

sourceTableName - A String which specifies the name of the source table to use in the query.

setTakeCount

public void setTakeCount(final Integer takeCount)

Sets the upper bound for the number of entities the query returns. If this value is not specified in a table query, by default a maximum of 1,000 entries will be returned.

If the value specified for the parameter is greater than 1,000, the query will throw a StorageException when executed.

Parameters:

takeCount - An Integer which represents the maximum number of entities for the table query to return.

take

public TableQuery take(final Integer take)

Defines the upper bound for the number of entities the query returns. If this value is not specified in a table query, by default a maximum of 1,000 entries will be returned.

If the value specified for the parameter is greater than 1,000, the query will throw a StorageException when executed.

Parameters:

take - An Integer which represents the maximum number of entities for the table query to return.

Returns:

A reference to the TableQuery<T> instance with the number of entities to return set.

where

public TableQuery where(final String filter)

Defines a filter expression for the table query. Only entities that satisfy the specified filter expression will be returned by the query. Setting a filter expression is optional; by default, all entities in the table are returned if no filter expression is specified in the table query.

Filter expressions for use with the where(final String filter) method can be created using fluent syntax with the overloaded generateFilterCondition(String propertyName, String operation, final boolean value) methods and combineFilters(String filterA, String operator, String filterB) method, using the comparison operators defined in QueryComparisons and the logical operators defined in Operators. Note that the first operand in a filter comparison must be a property name, and the second operand must evaluate to a constant. The PartitionKey and RowKey property values are types for comparison purposes. For example, to query all entities with a PartitionKey value of "AccessLogs" on table query :

The values that may be used in table queries are explained in more detail in the MSDN topic

Querying Tables and Entities, but note that the space characters within values do not need to be URL-encoded, as this will be done when the query is executed.

Note that no more than 15 discrete comparisons are permitted within a filter string.

Parameters:

filter - A String which specifies the filter expression to apply to the table query.

Returns:

A reference to the TableQuery<T> instance with the filter on entities to return set.

Applies to