Crear y usar claves de entidad

Esta API es compatible con los tiempos de ejecución de primera generación y se puede usar al actualizar a los tiempos de ejecución de segunda generación correspondientes. Si vas a actualizar al tiempo de ejecución de App Engine Go 1.12 o una versión posterior, consulta la guía de migración para obtener información sobre las opciones de migración de los servicios empaquetados antiguos.

Cada entidad de Datastore tiene una clave que la identifica de forma única. La clave consta de los siguientes componentes:

• El espacio de nombres de la entidad, que permite la arquitectura multicliente
• El tipo de la entidad, que la clasifica para las consultas de Datastore
• Una ruta de ancestro opcional que indica la ubicación de la entidad en la jerarquía de Datastore.

• Un identificador de la entidad individual, que puede ser

  • Una cadena key name
  • un ID numérico entero

Como el identificador forma parte de la clave de la entidad, se asocia permanentemente a la entidad y no se puede cambiar. Puedes asignar el identificador de dos formas:

• Especifica tu propia cadena de nombre de clave para la entidad.
• Permite que Datastore asigne automáticamente a la entidad un ID numérico entero.

No le pongas el nombre "key" a una propiedad. Este nombre está reservado para una propiedad especial que se usa para almacenar la clave del modelo. Aunque puede funcionar a nivel local, una propiedad llamada "key" impedirá que se implemente en App Engine.

Especificar el nombre de una clave de una entidad

Para asignar un nombre de clave a una entidad, proporciona un argumento stringID que no esté vacío a datastore.NewKey:

// Create a key with a key name "asalieri".
key := datastore.NewKey(
	ctx,        // context.Context
	"Employee", // Kind
	"asalieri", // String ID; empty means no string ID
	0,          // Integer ID; if 0, generate automatically. Ignored if string ID specified.
	nil,        // Parent Key; nil means no parent
)

Para que Datastore asigne un ID numérico automáticamente, usa un argumento stringID vacío:

// Create a key such as Employee:8261.
key := datastore.NewKey(ctx, "Employee", "", 0, nil)
// This is equivalent:
key = datastore.NewIncompleteKey(ctx, "Employee", nil)

Asignar identificadores

Puede configurar Datastore para que genere IDs automáticos mediante dos políticas de IDs automáticos diferentes:

• La política default genera una secuencia aleatoria de IDs no utilizados que se distribuyen de forma aproximadamente uniforme. Cada ID puede tener hasta 16 dígitos decimales.
• La política legacy crea una secuencia de IDs de números enteros más pequeños no consecutivos.

Si quieres mostrar los IDs de entidad al usuario o depender de su orden, lo mejor es usar la asignación manual.

Nota: En lugar de usar cadenas de nombres de claves o generar IDs numéricos automáticamente, es posible que las aplicaciones avanzadas quieran asignar sus propios IDs numéricos manualmente a las entidades que creen. Sin embargo, ten en cuenta que no hay nada que impida que Datastore asigne uno de tus IDs numéricos manuales a otra entidad. La única forma de evitar estos conflictos es que tu aplicación obtenga un bloque de IDs con la función datastore.AllocateIDs. El generador automático de IDs de Datastore registrará los IDs que se hayan asignado con esta función y evitará reutilizarlos para otra entidad, por lo que podrá usar estos IDs sin que haya conflictos.

Usar rutas de ancestro

Las entidades de Cloud Datastore forman un espacio estructurado jerárquicamente similar a la estructura de directorios de un sistema de archivos. Cuando creas una entidad, puedes designar otra entidad como principal. La nueva entidad será una secundaria de la entidad principal (ten en cuenta que, a diferencia de lo que ocurre en un sistema de archivos, la entidad principal no tiene por qué existir). Una entidad sin elemento superior es una entidad raíz. La asociación entre una entidad y su elemento superior es permanente y no se puede cambiar una vez que se ha creado la entidad. Cloud Datastore nunca asignará el mismo ID numérico a dos entidades con el mismo elemento superior ni a dos entidades raíz (aquellas que no tienen un elemento superior).

El elemento superior de una entidad, el elemento superior del elemento superior, etc., son sus ancestros. Sus elementos secundarios, los elementos secundarios de los elementos secundarios, etc., son sus descendientes. Una entidad raíz y todos sus descendientes pertenecen al mismo grupo de entidades. La secuencia de entidades que empieza con una entidad raíz y continúa de la entidad superior a la secundaria hasta llegar a una entidad determinada constituye la ruta de ancestros de esa entidad. La clave completa que identifica la entidad consta de una secuencia de pares tipo-identificador que especifican su ruta de ancestros y termina con los de la propia entidad:

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

En el caso de una entidad raíz, la ruta de ancestro está vacía y la clave se compone únicamente del tipo y el identificador de la entidad:

[Person:GreatGrandpa]

Este concepto se ilustra en el siguiente diagrama:

Para designar el elemento superior de una entidad, usa el argumento parent en datastore.NewKey. El valor de este argumento debe ser la clave de la entidad principal. En el siguiente ejemplo se crea una entidad de tipo Address y se designa una entidad Employee como su entidad principal:

// Create Employee entity
employee := &Employee{ /* ... */ }
employeeKey, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Employee", nil), employee)

// Use Employee as Address entity's parent
// and save Address entity to datastore
address := &Address{ /* ... */ }
addressKey := datastore.NewIncompleteKey(ctx, "Address", employeeKey)
_, err = datastore.Put(ctx, addressKey, address)