An NDB entity model can define properties . Entity properties are a little like data members of Python classes, a structured way to hold data; they are a little like fields in a database schema.
- Introduction
- Types
- Property Options
- Repeated Properties
- Date and Time Properties
- Structured Properties
- Computed Properties
- Google Protocol RPC Message Properties
Introduction
A typical application defines a data model by defining a class that
inherits from
Model
with some property class attributes.
For example,
from google.appengine.ext import ndb class Account(ndb.Model): username = ndb.StringProperty() userid = ndb.IntegerProperty() email = ndb.StringProperty()
Here,
username
,
userid
, and
email
are properties of
Account
.
There are several other property types. Some are handy for representing dates and times and have convenient auto-update features.
An application can adjust a property's behavior by specifying options on the property; these can ease validation, set defaults, or change query indexing.
A model can have more complex properties. Repeated properties are list-like. Structured properties are object-like. Read-only computed properties are defined via functions; this makes it easy to define a property in terms of one or more other properties. Expando models can define properties dynamically.
Types
NDB supports the following property types:
Property type | Description |
---|---|
IntegerProperty
| 64-bit signed integer |
FloatProperty
| Double-precision floating-point number |
BooleanProperty
| Boolean |
StringProperty
| Unicode string; up to 500 characters, indexed |
TextProperty
| Unicode string; unlimited length, not indexed |
BlobProperty
|
Uninterpreted byte string:
if you set
indexed=True
, up to 500 characters, indexed;
if
indexed
is
False
(the default), unlimited length, not indexed.
Optional keyword argument:
compressed
.
|
DateTimeProperty
| Date and time (see Date and Time Properties ) |
DateProperty
| Date (see Date and Time Properties ) |
TimeProperty
| Time (see Date and Time Properties ) |
GeoPtProperty
|
Geographical location. This is a
ndb.GeoPt
object.
The object
has attributes
lat
and
lon
, both floats.
You can construct one with two floats like
ndb.GeoPt(52.37, 4.88)
or with a string
ndb.GeoPt("52.37, 4.88")
.
(This is actually the same class as
db.GeoPt
)
|
KeyProperty
|
Datastore key
Optional keyword argument: kind= kind , to require that keys assigned to this property always have the indicated kind. May be a string or a Model subclass. |
BlobKeyProperty
|
Blobstore key
Corresponds to
BlobReferenceProperty
in the old db API, but the property value is a
BlobKey
instead of a
BlobInfo
; you can construct a
BlobInfo
from it using
BlobInfo(
blobkey
)
|
UserProperty
| User object. |
StructuredProperty
| Includes one kind of model inside another, by value (see Structured Properties ) |
LocalStructuredProperty
|
Like
StructuredProperty
,
but on-disk representation is an opaque blob and is not indexed
(see
Structured Properties
).
Optional keyword argument:
compressed
.
|
JsonProperty
|
Value is a Python object (such as a list or a dict or a string)
that is serializable using Python's
json
module;
the Datastore stores
the JSON serialization as a blob. Unindexed by default.
Optional keyword argument:
compressed
.
|
PickleProperty
|
Value is a Python object (such as a list or a dict or a string)
that is serializable using Python's pickle protocol; the Datastore stores
the pickle serialization as a blob. Unindexed by default.
Optional keyword argument:
compressed
.
|
GenericProperty
|
Generic value
Used mostly by the
Expando
class, but also usable explicitly. Its type may be any of
int
,
long
,
float
,
bool
,
str
,
unicode
,
datetime
,
Key
,
BlobKey
,
GeoPt
,
User
,
None
.
|
ComputedProperty
| Value computed from other properties by a user-defined function. (See Computed Properties .) |
Some of these properties have an optional keyword argument,
compressed
. If the property has
compressed=True
, then its data is compressed with gzip on disk.
It takes up less space but needs CPU to encode/decode on write and
read operations.
Both compression and decompression are "lazy"; a compressed property value will only be decompressed the first time you access it. If you read an entity containing a compressed property value and write it back without accessing the compressed property, it won't be decompressed and compressed at all. The in-context cache participates in this lazy scheme as well, but memcache always stores the compressed value for compressed properties.
Because of the extra CPU time needed for compression, it is usually best to use compressed properties only if the data would be too big to fit without it. Remember that gzip-based compression is typically not effective for images and other media data, since those formats already are compressed using a media-specific compression algorithm (e.g. JPEG for images).
Property Options
Most property types support some standard arguments. The first is an optional positional argument specifying the property's Datastore name. You can use this to give the property a different name in the Datastore than from the application's viewpoint. A common use for this is to reduce space in the Datastore, letting the Datastore use abbreviated property names while your code uses longer, more meaningful ones. For example,
class Employee(ndb.Model): full_name = ndb.StringProperty('n') retirement_age = ndb.IntegerProperty('r')
This is particularly useful for repeated properties for which you expect many values per entity.
In addition, most property types support the following keyword arguments:
Argument | Type | Default | Description |
---|---|---|---|
indexed
|
bool
|
Usually
True
|
Include property in Datastore's indexes; if
False
, values cannot be queried but writes are faster. Not all property types support indexing; setting
indexed
to
True
fails for these.
Unindexed properties cost fewer write ops than indexed properties. |
repeated
|
bool
|
False
| Property value is a Python list containing values of the underlying type (see Repeated Properties ). |
required
|
bool
|
False
|
Property must have a value specified.
Cannot be combined with
repeated=True
but can be combined with
default=True
.
|
default
| Property's underlying type | None |
Default value of property if none explicitly specified.
Cannot be combined with
repeated=True
but can be combined with
required=True
.
|
choices
| List of values of underlying type |
None
| Optional list of allowable values. |
validator
| Function |
None
|
Optional function to validate and possibly coerce the value. Will be called with arguments ( prop , value ) |