Crea y usa claves de entidad

Cada entidad se identifica mediante una clave que es única dentro de la instancia de Datastore de la aplicación y consta de lo siguiente:

  • categorías. En general, la categoría es el nombre de la clase de modelo a la que pertenece la entidad, pero puedes cambiarla por otra string si anulas el método de clase _get_kind().
  • identificador. Puedes especificar tu propio nombre clave como el identificador o dejar que Datastore genere un ID de número entero de forma automática.

Especifica tu propio nombre clave

En el ejemplo siguiente, se crea de forma implícita una clave con un identificador de string mediante el parámetro con nombre id:

appengine/standard/ndb/entities/snippets.py 
account = Account(
    username='Sandy', userid=1234, email='sandy@example.com',
    id='sandy@example.com')

return account.key.id()  # returns 'sandy@example.com'

De forma alternativa, puedes establecer el nombre de la clave directamente:

appengine/standard/ndb/entities/snippets.py 
account.key = ndb.Key('Account', 'sandy@example.com')

# You can also use the model class object itself, rather than its name,
# to specify the entity's kind:
account.key = ndb.Key(Account, 'sandy@example.com')

Permite que Datastore genere un ID para usar en la clave

Este código muestra cómo usar un ID generado de forma automática como clave:

appengine/standard/ndb/entities/snippets.py 
# note: no id kwarg
account = Account(username='Sandy', userid=1234, email='sandy@example.com')
account.put()
# account.key will now have a key of the form: ndb.Key(Account, 71321839)
# where the value 71321839 was generated by Datastore for us.

Usar la ruta principal en la clave

La secuencia de entidades que comienza con una entidad raíz y sigue de superior a secundario, hasta llegar a determinada entidad, constituye la ruta principal de esa entidad. Una entidad, la superior, la superior de la superior, y así sucesivamente, son las principales de la entidad. Las entidades en Datastore forman un espacio de claves jerárquico similar a la estructura de directorios jerárquica de un sistema de archivos.

La clave completa que identifica a una entidad consta de una secuencia de pares de categoría-identificador que especifican la ruta del principal y finalizan con los de la entidad en sí misma. El método constructor para la clase Key acepta esa secuencia de categorías e identificadores, y muestra un objeto que representa la clave para la entidad correspondiente.

El ejemplo siguiente muestra un servicio de blogging que almacena mensajes por revisión. Los mensajes se organizan en cuentas y las revisiones en mensajes.

appengine/standard/ndb/entities/snippets.py 
class Revision(ndb.Model):
    message_text = ndb.StringProperty()
... 
ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '1')
ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '2')
ndb.Key('Account', 'larry@example.com', 'Message', 456, 'Revision', '1')
ndb.Key('Account', 'larry@example.com', 'Message', 789, 'Revision', '2')

En la muestra, ('Account', 'sandy@example.com'), ('Message', 123) y ('Revision', '1') son todos ejemplos de pares de categoría-identificador.

Ten en cuenta que Message no es una clase de modelo; solo se usa como una forma de agrupar revisiones, no para almacenar datos.

Como se muestra en el código de muestra, la categoría de la entidad se designa por el último par de categoría-nombre de la lista: ndb.Key('Revision', '1').

Usa parámetros con nombre

Puedes usar el parámetro con nombre parent para designar cualquier entidad en la ruta del principal directamente. Todas las notaciones siguientes representan la misma clave:

appengine/standard/ndb/entities/snippets.py 
ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '1')

ndb.Key('Revision', '1', parent=ndb.Key(
    'Account', 'sandy@example.com', 'Message', 123))

ndb.Key('Revision', '1', parent=ndb.Key(
    'Message', 123, parent=ndb.Key('Account', 'sandy@example.com')))

Especificar una entidad raíz

Para una entidad raíz, la ruta principal está vacía y la clave consta solo de la categoría y del identificador de la entidad.

appengine/standard/ndb/entities/snippets.py 
sandy_key = ndb.Key(Account, 'sandy@example.com')

Especificar una entidad con ancestros

Para insertar un mensaje nuevo con claves superiores, haz lo siguiente:

appengine/standard/ndb/entities/snippets.py 
account_key = ndb.Key(Account, 'sandy@example.com')

# Ask Datastore to allocate an ID.
new_id = ndb.Model.allocate_ids(size=1, parent=account_key)[0]

# Datastore returns us an integer ID that we can use to create the message
# key
message_key = ndb.Key('Message', new_id, parent=account_key)

# Now we can put the message into Datastore
initial_revision = Revision(
    message_text='Hello', id='1', parent=message_key)
initial_revision.put()

Para las claves que se crearon con un superior, el método parent() muestra una clave que representa la entidad principal:

appengine/standard/ndb/entities/snippets.py 
message_key = initial_revision.key.parent()

Usa los ID de clave numérica

Puedes crear una entidad sin especificar un ID, en cuyo caso el almacén de datos genera de forma automática un ID numérico. Si eliges especificar algunos ID y, luego, permites que Datastore genere de forma automática algunos ID, podrías infringir el requisito de claves únicas. A fin de evitar esto, reserva un rango de números que se usen para elegir los ID o usa los ID de string si quieres evitar este problema por completo.

Para reservar un rango de ID, usa el método de clase allocate_ids() de la clase de modelo:

  • para asignar una cantidad específica de ID
  • para asignar todos los ID hasta un valor máximo dado

Asigna ID

Para asignar 100 ID a una clase modelo determinada MyModel, haz lo siguiente:

appengine/standard/ndb/entities/snippets.py 
first, last = MyModel.allocate_ids(100)

Para asignar 100 ID a entidades con clave superior p, haz lo siguiente:

appengine/standard/ndb/entities/snippets.py 
first, last = MyModel.allocate_ids(100, parent=p)

Los valores que se muestran, first y last, son los primeros y últimos ID (incluidos) que se asignan. Puedes usarlos para construir claves de la siguiente manera:

appengine/standard/ndb/entities/snippets.py 
keys = [ndb.Key(MyModel, id) for id in range(first, last+1)]

Se garantiza que el generador de ID interno del almacén de datos no ha mostrado estas claves antes ni que se mostrarán en llamadas futuras al generador de ID interno. Sin embargo, el método allocate_ids() no verifica si los ID que se muestran están presentes en el almacén de datos, solo interactúa con el generador de ID.

Para asignar todos los ID hasta un valor máximo dado, haz lo siguiente:

appengine/standard/ndb/entities/snippets.py 
first, last = MyModel.allocate_ids(max=N)

Este formulario garantiza que todos los ID menores o iguales a N se consideran asignados. Los valores que se muestran, first y last, indican el rango de ID que reserva esta operación. No es un error intentar reservar los ID ya asignados. Si eso sucede, first indica el primer ID que aún no está asignado, y last es el último ID asignado.