Tables store data as collections of entities. Entities are similar to rows. An entity has a primary key and a set of properties. A property is a named, typed-value pair, similar to a column.
The Table service does not enforce any schema for tables, so two entities in the same table may have different sets of properties. Developers may choose to enforce a schema on the client side. A table may contain any number of entities.
Zend_Service_WindowsAzure_Storage_Table provides 2 ways of
working with entities:
Enforced schema
No enforced schema
All examples will make use of the following enforced schema class.
Example 893. Enforced schema used in samples
<?php
class SampleEntity extends Zend_Service_WindowsAzure_Storage_TableEntity
{
/**
* @azure Name
*/
public $Name;
/**
* @azure Age Edm.Int64
*/
public $Age;
/**
* @azure Visible Edm.Boolean
*/
public $Visible = false;
}
Note that if no schema class is passed into table storage methods,
Zend_Service_WindowsAzure_Storage_Table automatically works with
Zend_Service_WindowsAzure_Storage_DynamicTableEntity.
To enforce a schema on the client side using the
Zend_Service_WindowsAzure_Storage_Table class, you can create
a class which inherits
Zend_Service_WindowsAzure_Storage_TableEntity. This class
provides some basic functionality for the
Zend_Service_WindowsAzure_Storage_Table class to work with a
client-side schema.
Base properties provided by
Zend_Service_WindowsAzure_Storage_TableEntity are:
PartitionKey (exposed through
getPartitionKey()andsetPartitionKey())RowKey (exposed through
getRowKey()andsetRowKey())Timestamp (exposed through
getTimestamp()andsetTimestamp())Etag value (exposed through
getEtag()andsetEtag())
Here's a sample class inheriting
Zend_Service_WindowsAzure_Storage_TableEntity:
Example 894. Sample enforced schema class
<?php
class SampleEntity extends Zend_Service_WindowsAzure_Storage_TableEntity
{
/**
* @azure Name
*/
public $Name;
/**
* @azure Age Edm.Int64
*/
public $Age;
/**
* @azure Visible Edm.Boolean
*/
public $Visible = false;
}
The Zend_Service_WindowsAzure_Storage_Table class will map
any class inherited from
Zend_Service_WindowsAzure_Storage_TableEntity to Windows
Azure table storage entities with the correct data type and property name. All there
is to storing a property in Windows Azure is adding a docblock comment to a public
property or public getter/setter, in the following format:
Example 895. Enforced property
<?php
/**
* @azure <property name in Windows Azure> <optional property type>
*/
public $<property name in PHP>;
Let's see how to define a propety "Age" as an integer on Windows Azure table storage:
Note that a property does not necessarily have to be named the same on Windows Azure table storage. The Windows Azure table storage property name can be defined as well as the type.
The following data types are supported:
Edm.Binary- An array of bytes up to 64 KB in size.Edm.Boolean- A boolean value.Edm.DateTime- A 64-bit value expressed as Coordinated Universal Time (UTC). The supported DateTime range begins from 12:00 midnight, January 1, 1601 A.D. (C.E.), Coordinated Universal Time (UTC). The range ends at December 31st, 9999.Edm.Double- A 64-bit floating point value.Edm.Guid- A 128-bit globally unique identifier.Edm.Int32- A 32-bit integer.Edm.Int64- A 64-bit integer.Edm.String- A UTF-16-encoded value. String values may be up to 64 KB in size.
To use the Zend_Service_WindowsAzure_Storage_Table class
without defining a schema, you can make use of the
Zend_Service_WindowsAzure_Storage_DynamicTableEntity class.
This class inherits
Zend_Service_WindowsAzure_Storage_TableEntity like an
enforced schema class does, but contains additional logic to make it dynamic and not
bound to a schema.
Base properties provided by
Zend_Service_WindowsAzure_Storage_DynamicTableEntity are:
PartitionKey (exposed through
getPartitionKey()andsetPartitionKey())RowKey (exposed through
getRowKey()andsetRowKey())Timestamp (exposed through
getTimestamp()andsetTimestamp())Etag value (exposed through
getEtag()andsetEtag())
Other properties can be added on the fly. Their Windows Azure table storage type will be determined on-the-fly:
Example 897. Dynamicaly adding properties to Zend_Service_WindowsAzure_Storage_DynamicTableEntity
<?php
$target = new Zend_Service_WindowsAzure_Storage_DynamicTableEntity(
'partition1', '000001'
);
$target->Name = 'Name'; // Will add property "Name" of type "Edm.String"
$target->Age = 25; // Will add property "Age" of type "Edm.Int32"
Optionally, a property type can be enforced:
Example 898. Forcing property types on Zend_Service_WindowsAzure_Storage_DynamicTableEntity
<?php
$target = new Zend_Service_WindowsAzure_Storage_DynamicTableEntity(
'partition1', '000001'
);
$target->Name = 'Name'; // Will add property "Name" of type "Edm.String"
$target->Age = 25; // Will add property "Age" of type "Edm.Int32"
// Change type of property "Age" to "Edm.Int32":
$target->setAzurePropertyType('Age', 'Edm.Int64');
The Zend_Service_WindowsAzure_Storage_Table class
automatically works with
Zend_Service_WindowsAzure_Storage_TableEntity if no specific
class is passed into Table Storage methods.
Using the following code, an entity can be inserted into a table named "testtable". Note that the table has already been created before.
Example 899. Inserting an entity
<?php
$entity = new SampleEntity ('partition1', 'row1');
$entity->FullName = "Maarten";
$entity->Age = 25;
$entity->Visible = true;
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
'table.core.windows.net', 'myaccount', 'myauthkey'
);
$result = $storageClient->insertEntity('testtable', $entity);
// Check the timestamp and etag of the newly inserted entity
echo 'Timestamp: ' . $result->getTimestamp() . "\n";
echo 'Etag: ' . $result->getEtag() . "\n";
Using the following code, an entity can be retrieved by partition key and row key. Note that the table and entity have already been created before.
Example 900. Retrieving an entity by partition key and row key
<?php
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity= $storageClient->retrieveEntityById(
'testtable', 'partition1', 'row1', 'SampleEntity'
);
Using the following code, an entity can be updated. Note that the table and entity have already been created before.
Example 901. Updating an entity
<?php
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity = $storageClient->retrieveEntityById(
'testtable', 'partition1', 'row1', 'SampleEntity'
);
$entity->Name = 'New name';
$result = $storageClient->updateEntity('testtable', $entity);
If you want to make sure the entity has not been updated before, you can make sure the Etag of the entity is checked. If the entity already has had an update, the update will fail to make sure you do not overwrite any newer data.
Example 902. Updating an entity (with Etag check)
<?php
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity = $storageClient->retrieveEntityById(
'testtable', 'partition1', 'row1', 'SampleEntity'
);
$entity->Name = 'New name';
// last parameter instructs the Etag check:
$result = $storageClient->updateEntity('testtable', $entity, true);
Using the following code, an entity can be deleted. Note that the table and entity have already been created before.
Example 903. Deleting an entity
<?php
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity = $storageClient->retrieveEntityById(
'testtable', 'partition1', 'row1', 'SampleEntity'
);
$result = $storageClient->deleteEntity('testtable', $entity);
Queries in Zend_Service_WindowsAzure_Storage_Table table
storage can be performed in two ways:
By manually creating a filter condition (involving learning a new query language)
By using the fluent interface provided by the
Zend_Service_WindowsAzure_Storage_Table
Using the following code, a table can be queried using a filter condition. Note that the table and entities have already been created before.
Example 904. Performing queries using a filter condition
<?php
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entities = $storageClient->storageClient->retrieveEntities(
'testtable',
'Name eq \'Maarten\' and PartitionKey eq \'partition1\'',
'SampleEntity'
);
foreach ($entities as $entity) {
echo 'Name: ' . $entity->Name . "\n";
}
Using the following code, a table can be queried using a fluent interface. Note that the table and entities have already been created before.
Example 905. Performing queries using a fluent interface
<?php
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entities = $storageClient->storageClient->retrieveEntities(
'testtable',
$storageClient->select()
->from($tableName)
->where('Name eq ?', 'Maarten')
->andWhere('PartitionKey eq ?', 'partition1'),
'SampleEntity'
);
foreach ($entities as $entity) {
echo 'Name: ' . $entity->Name . "\n";
}
This topic demonstrates how to use the table entity group transaction features provided by Windows Azure table storage. Windows Azure table storage supports batch transactions on entities that are in the same table and belong to the same partition group. A transaction can include at most 100 entities.
The following example uses a batch operation (transaction) to insert a set of entities into the "testtable" table. Note that the table has already been created before.
Example 906. Executing a batch operation
<?php
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
'table.core.windows.net', 'myaccount', 'myauthkey'
);
// Start batch
$batch = $storageClient->startBatch();
// Insert entities in batch
$entities = generateEntities();
foreach ($entities as $entity) {
$storageClient->insertEntity($tableName, $entity);
}
// Commit
$batch->commit();