Understanding the Table service data model
The Table service offers structured storage in the form of tables. The following sections outline the Table service data model.
Storage Account
A storage account is a globally unique entity within the storage system. The storage account is the parent namespace for the Table service, and is the basis for authorization. You can create any number of tables within a given storage account, as long as each table is uniquely named.
The storage account must always be specified in the request URI. The base URI for accessing the Table service is as follows:
https://myaccount.table.core.windows.net
Tables, Entities, and Properties
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 name, 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.
Table Names
Table names must conform to these rules:
Table names must be unique within an account.
Table names may contain only alphanumeric characters.
Table names cannot begin with a numeric character.
Table names are case-insensitive.
Table names must be from 3 to 63 characters long.
Some table names are reserved, including "tables". Attempting to create a table with a reserved table name returns error code 404 (Bad Request).
These rules are also described by the regular expression "^[A-Za-z][A-Za-z0-9]{2,62}$".
Table names preserve the case with which they were created, but are case-insensitive when used.
Property Names
Property names are case-sensitive strings up to 255 characters in size. Property names should follow naming rules for C# identifiers.
Note
Some C# identifiers are not valid according to the XML specification. These identifiers may not be used in property names, because property names are sent via an XML payload in a request against the Table service.
Important
Property names are passed to the Table service within a URL. Certain characters must be percent-encoded to appear in a URL, using UTF-8 (preferred) or MBCS. This encoding occurs automatically when you use the Azure Storage client libraries. However, there are certain characters that are not valid in URL paths even when encoded. These characters cannot appear in property names. Code points like \uE000, while valid in NTFS filenames, are not valid Unicode characters, so they cannot be used. In addition, some ASCII or Unicode characters, like control characters (0x00 to 0x1F, \u0081, etc.), are also not allowed. For rules governing Unicode strings in HTTP/1.1 see:
Note
Beginning with version 2009-04-14, the Table service no longer supports including the dash (-) character in property names.
Property Limitations
An entity can have up to 255 properties, including 3 system properties described in the following section. Therefore, the user may include up to 252 custom properties, in addition to the 3 system properties. The combined size of all data in an entity's properties cannot exceed 1 MiB.
System Properties
An entity always has the following system properties:
PartitionKey
propertyRowKey
propertyTimestamp
property
These system properties are automatically included for every entity in a table. The names of these properties are reserved and cannot be changed. The developer is responsible for inserting and updating the values of PartitionKey
and RowKey
. The server manages the value of Timestamp
, which cannot be modified.
Characters Disallowed in Key Fields
The following characters are not allowed in values for the PartitionKey
and RowKey
properties:
The forward slash (/) character
The backslash (\) character
The number sign (#) character
The question mark (?) character
Control characters from U+0000 to U+001F, including:
- The horizontal tab (\t) character
- The linefeed (\n) character
- The carriage return (\r) character
Control characters from U+007F to U+009F
PartitionKey Property
Tables are partitioned to support load balancing across storage nodes. A table's entities are organized by partition. A partition is a consecutive range of entities possessing the same partition key value. The partition key is a unique identifier for the partition within a given table, specified by the PartitionKey
property. The partition key forms the first part of an entity's primary key. The partition key may be a string value up to 1024 characters in size.
You must include the PartitionKey
property in every insert, update, and delete operation.
RowKey Property
The second part of the primary key is the row key, specified by the RowKey
property. The row key is a unique identifier for an entity within a given partition. Together the PartitionKey
and RowKey
uniquely identify every entity within a table.
The row key is a string value that may be up to 1024 characters in size.
You must include the RowKey
property in every insert, update, and delete operation.
Timestamp Property
The Timestamp
property is a DateTime
value that is maintained on the server side to record the time an entity was last modified. The Table service uses the Timestamp
property internally to provide optimistic concurrency. The value of the Timestamp
property for an entity advances each time the entity is modified. This property should not be set on insert or update operations (the value will be ignored).
The Timestamp
property must be expressed in one of the accepted ISO 8601 UTC formats. For more information about accepted UTC formats, see Formatting DateTime values.
Property Types
The Table service supports a subset of data types defined by the OData Protocol Specification. The following table shows the supported property types for the Table service:
OData Data Type | Common Language Runtime type | Details |
---|---|---|
Edm.Binary |
byte[] |
An array of bytes up to 64 KiB in size. |
Edm.Boolean |
bool |
A Boolean value. |
Edm.DateTime |
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.), UTC. The range ends at December 31, 9999. For more information, see Formatting DateTime values. |
Edm.Double |
double |
A 64-bit floating point value. |
Edm.Guid |
Guid |
A 128-bit globally unique identifier. |
Edm.Int32 |
Int32 oder int |
A 32-bit integer. |
Edm.Int64 |
Int64 oder long |
A 64-bit integer. |
Edm.String |
String |
A UTF-16-encoded value. String values may be up to 64 KiB in size. Note that the maximum number of characters supported is about 32 K or less. |
By default a property is created as type String
, unless you specify a different type. To explicitly type a property, specify its data type by using the appropriate OData data type for an Insert Entity oder Update Entity operation. For more information, see Inserting and Updating Entities.
The Table service does not persist null
values for properties. When querying entities, the above property types are all non-nullable. When writing entities, the above property types are all nullable, and any property with a null
value is handled as if the payload did not contain that property.
For examples that show how to filter on the various property types in a query request URI, see Querying Tables and Entities.