# Datastore Statistics in Java - Google App Engine - Google Code

English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Datastore Statistics in Java

The datastore maintains statistics about the data stored for an application, such as how many entities there are of a given kind, or how much space is used by property values of a given type. You can view these statistics in the Administration Console, under Datastore > Statistics.

You can also access these values programmatically within the application by querying for specially named entites using the datastore API. Each statistic is accessible as an entity whose kind name begins and ends with two underscores. For example, each app has exactly one entity of the kind `__Stat_Total__` that represents statistics about all of the entities in the datastore in total. Each statistic entity has the following properties:

- `count`, the number of items considered by the statistic (a long integer)
- `bytes`, the total size of the items for this statistic (a long integer)
- `timestamp`, the time of the most recent update to the statistic (a date-time value)

Some statistic kinds also have additional properties, listed below.

A Java application can access statistic entities using the low-level datastore API. For example:

    import com.google.appengine.api.datastore.DatastoreService;
    import com.google.appengine.api.datastore.DatastoreServiceFactory;
    import com.google.appengine.api.datastore.Entity;
    import com.google.appengine.api.datastore.Query;

    // ...
    DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
    Entity globalStat = datastore.prepare(new Query("__Stat_Total__")).asSingleEntity();
    Long totalBytes = (Long) globalStat.getProperty("bytes");
    Long totalEntities = (Long) globalStat.getProperty("count");

When the statistics system creates new statistic entities, it does not delete the old ones right away. The best way to get a consistent view of the statistics is to query for the `__Stat_Total__` entity with the most recent `timestamp`, then use that timestamp value as a filter when fetching other statistic entities.

The statistic entities are included in the calculated statistic values. Statistic entities take up space relative to the number of unique kinds and property names used by the application.

The statistics system will also create statistics specific to each namespace. Note that if an application does not use datastore namespaces then namespace specific statistics will not be created. Namespace specific stats are found in the namespace that they're specific to. The kind names for namespace specific stats are prefixed with `__Stat_Ns_` and have the same corresponding suffix as application wide statistics kinds.

The complete list of available statistics is as follows:

Statistic | Stat Entity Kind | Description
--- | --- | ---
all entities | `__Stat_Total__` Namespace specific entry: `__Stat_Ns_Total__` | All entities.

all entities in a namespace

`__Stat_Namespace__`

Note that `__Stat_Namespace__` entities are created for each namespace encountered and are only found in the empty string namespace.

All entities in a namespace.

- `subject_namespace`, the namespace represented (a string)

entities of a kind

`__Stat_Kind__`

Namespace specific entry:
`__Stat_Ns_Kind__`

Entities of a kind; one stat entity for each kind of entity stored. Additional properties:

- `kind_name`, the name of the kind represented (a string)

root entities of a kind

`__Stat_Kind_IsRootEntity__`

Namespace specific entry:
`__Stat_Ns_Kind_IsRootEntity__`

Entities of a kind that are entity group root entities (have no ancestor parent); one stat entity for each kind of entity stored. Additional properties:

- `kind_name`, the name of the kind represented (a string)

non-root entities of a kind

`__Stat_Kind_NotRootEntity__`

Namespace specific entry:
`__Stat_Ns_Kind_NotRootEntity__`

Entities of a kind that are not entity group root entities (have an ancestor parent); one stat entity for each kind of entity stored. Additional properties:

- `kind_name`, the name of the kind represented (a string)

properties of a type

`__Stat_PropertyType__`

Namespace specific entry:
`__Stat_Ns_PropertyType__`

Properties of a value type across all entities; one stat entity per value type. Additional properties:

- `property_type`, the name of the value type (a string)

properties of a type per kind

`__Stat_PropertyType_Kind__`

Namespace specific entry:
`__Stat_Ns_PropertyType_Kind__`

Properties of a value type across entities of a given kind; one stat entity per combination of property type and kind. Additional properties:

- `property_type`, the name of the value type (a string)
- `kind_name`, the name of the kind represented (a string)

properties with a name

`__Stat_PropertyName_Kind__`

Namespace specific entry:
`__Stat_Ns_PropertyName_Kind__`

Properties with a given name across entities of a given kind; one stat entity per combination of unique property name and kind. Additional properties:

- `property_name`, the name of the property (a string)
- `kind_name`, the name of the kind represented (a string)

properties of a type and with a name

`__Stat_PropertyType_PropertyName_Kind__`

Namespace specific entry:
`__Stat_Ns_PropertyType_PropertyName_Kind__`

Properties with a given name and of a given value type across entities of a given kind; one stat entity per combination of property name, value type and kind that exists in the datastore. Additional properties:

- `property_type`, the name of the value type (a string)
- `property_name`, the name of the property (a string)
- `kind_name`, the name of the kind represented (a string)

Some statistics refer to datastore property value types by name, as strings. These names are as follows:

- `"Blob"`
- `"BlobKey"`
- `"Boolean"`
- `"Category"`
- `"Date/Time"`
- `"Email"`
- `"Float"`
- `"GeoPt"`
- `"IM"`
- `"Integer"`
- `"Key"`
- `"Link"`
- `"NULL"`
- `"PhoneNumber"`
- `"PostalAddress"`
- `"Rating"`
- `"ShortBlob"`
- `"String"`
- `"Text"`
- `"User"`

Note that `__Stat_Namespace__` entities contain the same information found in `__Stat_Ns_Total__` records. `__State_Namespace__` entities are stored in the empty namespace and contain a `subject_namespace` field describing the namespace to which they belong. `__Stat_Ns_Total__` records are stored in the namespace to which they refer, and thus do not contain a `subject_namespace` field. Hence, a query on kind `__Stat_Namespace__` (from the empty string namespace) ordered descending by `bytes` will list the namespaces that consume the largest storage first. Since queries across namespaces are not possible, any query for `__State_Ns_Total__` entities will only ever produce at most single record.