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<T extends TableEntity> extends Object
TableQuery instance aggregates the query
parameters to use when the query is executed. One of the execute or executeSegmented
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(java.lang.Class<T>) static factory method and the where(java.lang.String),
select(java.lang.String[]), and take(java.lang.Integer) 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
TableQuery instance that executes on the named table with entities of the specified TableEntity
implementing type. Use the where(java.lang.String) method to specify a filter expression for the entities returned. Use the
select(java.lang.String[]) method to specify the table entity properties to return. Use the take(java.lang.Integer) method to limit the
number of entities returned by the query. Note that nothing prevents calling these methods more than once on a
TableQuery, so the values saved in the TableQuery will be the last encountered in order of
execution.
As an example, you could construct a table query using fluent syntax:
TableQuery<TableServiceEntity> myQuery = TableQuery.from("Products", DynamicTableEntity.class)
.where("(PartitionKey eq 'ProductsMNO') and (RowKey ge 'Napkin')")
.take(25)
.select(new String[] {"InventoryCount"});
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(java.lang.String) method or setFilterString(java.lang.String) method can be created using
fluent syntax with the overloaded generateFilterCondition(java.lang.String, java.lang.String, boolean) methods and combineFilters(java.lang.String, java.lang.String, java.lang.String) method, using
the comparison operators defined in TableQuery.QueryComparisons and the logical operators defined in TableQuery.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 String 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(Class) constructor and 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, the caller may specify TableServiceEntity .class as
the class type.
| Modifier and Type | Class and Description |
|---|---|
static class |
TableQuery.Operators
A static class that maps identifiers to filter expression operators.
|
static class |
TableQuery.QueryComparisons
A static class that maps identifiers to filter property comparison operators.
|
| Constructor and Description |
|---|
TableQuery()
Initializes an empty
TableQuery instance. |
TableQuery(Class<T> clazzType)
Initializes a
TableQuery with the specified table entity type. |
| Modifier and Type | Method and Description |
|---|---|
static 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> |
from(Class<T> clazzType)
A static factory method that constructs a
TableQuery instance and defines its table entity type. |
static String |
generateFilterCondition(String propertyName,
String operation,
boolean value)
Generates a property filter condition string for a
boolean value. |
static String |
generateFilterCondition(String propertyName,
String operation,
byte[] value)
Generates a property filter condition string for a
byte[] value. |
static String |
generateFilterCondition(String propertyName,
String operation,
Byte[] value)
Generates a property filter condition string for a
Byte[] value. |
static String |
generateFilterCondition(String propertyName,
String operation,
Date value)
Generates a property filter condition string for a
java.util.Date value. |
static String |
generateFilterCondition(String propertyName,
String operation,
double value)
Generates a property filter condition string for a
double value. |
static String |
generateFilterCondition(String propertyName,
String operation,
int value)
Generates a property filter condition string for an
int value. |
static String |
generateFilterCondition(String propertyName,
String operation,
long value)
Generates a property filter condition string for a
long value. |
static String |
generateFilterCondition(String propertyName,
String operation,
String value)
Generates a property filter condition string for a
String value. |
static String |
generateFilterCondition(String propertyName,
String operation,
String value,
EdmType edmType)
Generates a property filter condition string.
|
static String |
generateFilterCondition(String propertyName,
String operation,
UUID value)
Generates a property filter condition string for a
UUID value. |
protected UriQueryBuilder |
generateQueryBuilder()
Reserved for internal use.
|
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.
|
String |
getFilterString()
Gets the filter expression specified in the table query.
|
protected 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.
|
TableQuery<T> |
select(String[] columns)
Defines the property names of the table entity properties to return when the table query is executed.
|
void |
setClazzType(Class<T> clazzType)
Sets the class type of the table entities returned by the query.
|
void |
setColumns(String[] columns)
Sets the property names of the table entity properties to return when the table query is executed.
|
void |
setFilterString(String filterString)
Sets the filter expression to use in the table query.
|
protected void |
setSourceTableName(String sourceTableName)
Sets the name of the source table for the table query.
|
void |
setTakeCount(Integer takeCount)
Sets the upper bound for the number of entities the query returns.
|
TableQuery<T> |
take(Integer take)
Defines the upper bound for the number of entities the query returns.
|
TableQuery<T> |
where(String filter)
Defines a filter expression for the table query.
|
public TableQuery()
TableQuery instance. This table query cannot be executed without
setting a table entity type.public TableQuery(Class<T> clazzType)
TableQuery with the specified table entity type. Callers may specify
TableServiceEntity.class as the class type parameter if no more specialized type is
required.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.public static <T extends TableEntity> TableQuery<T> from(Class<T> clazzType)
TableQuery instance and defines its table entity type. The
method returns the TableQuery instance reference, allowing additional methods to be chained to modify the
query.
The created TableQuery instance is specialized for table entities of the specified class type T. Callers
may specify TableServiceEntity .class as the class type parameter if no more specialized
type is required.
clazzType - The java.lang.Class of the class T implementing the TableEntity
interface that represents the table entity type for the query.TableQuery instance with the entity type specialization set.public static String generateFilterCondition(String propertyName, String operation, boolean value)
boolean 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:
String condition = generateFilterCondition("BooleanProperty", QueryComparisons.EQUAL, false);
This statement sets condition to the following value:
BooleanProperty eq false
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.String which represents the formatted filter condition.public static String generateFilterCondition(String propertyName, String operation, byte[] value)
byte[] 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:
String condition = generateFilterCondition("ByteArray", QueryComparisons.EQUAL, new byte[] {0x01, 0x0f});
This statement sets condition to the following value:
ByteArray eq X'010f'
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.String which represents the formatted filter condition.public static String generateFilterCondition(String propertyName, String operation, Byte[] value)
Byte[] 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:
String condition = generateFilterCondition("ByteArray", QueryComparisons.EQUAL, new Byte[] {0x01, 0xfe});
This statement sets condition to the following value:
ByteArray eq X'01fe'
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.String which represents the formatted filter condition.public static String generateFilterCondition(String propertyName, String operation, Date value)
java.util.Date 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:
String condition = generateFilterCondition("FutureDate", QueryComparisons.GREATER_THAN, new Date());
This statement sets condition to something like the following value:
FutureDate gt datetime'2013-01-31T09:00:00'
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.String which represents the formatted filter condition.public static String generateFilterCondition(String propertyName, String operation, double value)
double 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:
String condition = generateFilterCondition("Circumference", QueryComparisons.EQUAL, 2 * 3.141592);
This statement sets condition to the following value:
Circumference eq 6.283184
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.String which represents the formatted filter condition.public static String generateFilterCondition(String propertyName, String operation, int value)
int 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:
String condition = generateFilterCondition("Population", QueryComparisons.GREATER_THAN, 1000);
This statement sets condition to the following value:
Population gt 1000
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.String which represents the formatted filter condition.public static String generateFilterCondition(String propertyName, String operation, long value)
long 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:
String condition = generateFilterCondition("StellarMass", QueryComparisons.GREATER_THAN, 7000000000L);
This statement sets condition to the following value:
StellarMass gt 7000000000
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.String which represents the formatted filter condition.public static String generateFilterCondition(String propertyName, String operation, String value)
String 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:
String condition = generateFilterCondition("Platform", QueryComparisons.EQUAL, "Azure");
This statement sets condition to the following value:
Platform eq 'Azure'
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.String which represents the formatted filter condition.public static String generateFilterCondition(String propertyName, String operation, String value, EdmType edmType)
EdmType.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.String which represents the formatted filter condition.public static String generateFilterCondition(String propertyName, String operation, UUID value)
UUID 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:
String condition = generateFilterCondition("Identity", QueryComparisons.EQUAL, UUID.fromString(
"c9da6455-213d-42c9-9a79-3e9149a57833"));
This statement sets condition to the following value:
Identity eq guid'c9da6455-213d-42c9-9a79-3e9149a57833'
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.String which represents the formatted filter condition.public static String combineFilters(String filterA, String operator, String filterB)
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.String which represents the combined filter expression.public Class<T> getClazzType()
java.lang.Class of the class T that represents the table entity type for
the query.public String[] getColumns()
setColumns(java.lang.String[]) or select(java.lang.String[]) methods with a
array of property names as parameter.
Note that the system properties PartitionKey, RowKey, and Timestamp are
automatically requested from the table service whether specified in the TableQuery or not.
String objects which represents the property names of the table entity properties to
return in the query.public String getFilterString()
setFilterString(java.lang.String) or where(java.lang.String) methods.String which represents the filter expression used in the query.protected String getSourceTableName()
String which represents the name of the source table used in the query.public Integer getTakeCount()
setTakeCount(java.lang.Integer) or take(java.lang.Integer) methods.
If the value returned by getTakeCount is greater than 1,000, the query will throw a
StorageException when executed.
Integer which represents the maximum number of entities for the table query to return.public TableQuery<T> select(String[] columns)
select 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 PartitionKey, RowKey, and Timestamp are
automatically requested from the table service whether specified in the TableQuery or not.
columns - An array of String objects which specify the property names of the table entity properties
to return when the query is executed.TableQuery instance with the table entity properties to return set.public void setClazzType(Class<T> clazzType)
Callers may specify TableServiceEntity.class as the class type parameter if no more
specialized type is required.
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,public void setColumns(String[] columns)
Note that the system properties PartitionKey, RowKey, and Timestamp are
automatically requested from the table service whether specified in the TableQuery or not.
columns - An array of String objects which specify the property names of the table entity properties
to return when the query is executed.public void setFilterString(String filterString)
Filter expressions for use with the setFilterString(java.lang.String) method can be created using fluent syntax with the
overloaded generateFilterCondition(java.lang.String, java.lang.String, boolean) methods and combineFilters(java.lang.String, java.lang.String, java.lang.String) method, using the comparison
operators defined in TableQuery.QueryComparisons and the logical operators defined in TableQuery.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 String types for comparison purposes. For
example, to query all entities with a PartitionKey value of "AccessLogs" on table query myQuery:
myQuery.setFilterString("PartitionKey eq 'AccessLogs'");
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.
filterString - A String which represents the filter expression to use in the query.protected void setSourceTableName(String sourceTableName)
sourceTableName - A String which specifies the name of the source table to use in the query.public void setTakeCount(Integer takeCount)
If the value specified for the takeCount parameter is greater than 1,000, the query will throw a
StorageException when executed.
takeCount - An Integer which represents the maximum number of entities for the table query to return.public TableQuery<T> take(Integer take)
If the value specified for the take parameter is greater than 1,000, the query will throw a
StorageException when executed.
take - An Integer which represents the maximum number of entities for the table query to return.TableQuery instance with the number of entities to return set.public TableQuery<T> where(String filter)
Filter expressions for use with the where(java.lang.String) method can be created using fluent syntax with the overloaded
generateFilterCondition(java.lang.String, java.lang.String, boolean) methods and combineFilters(java.lang.String, java.lang.String, java.lang.String) method, using the comparison operators
defined in TableQuery.QueryComparisons and the logical operators defined in TableQuery.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 String types for comparison purposes. For example, to
query all entities with a PartitionKey value of "AccessLogs" on table query myQuery:
myQuery = myQuery.where("PartitionKey eq 'AccessLogs'");
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.
filter - A String which specifies the filter expression to apply to the table query.TableQuery instance with the filter on entities to return set.protected UriQueryBuilder generateQueryBuilder() throws StorageException
UriQueryBuilder object representing the table query.UriQueryBuilder object representing the table query.StorageException - if an error occurs in adding or encoding the query parameters.Copyright © 2019. All rights reserved.