Entidades, propiedades y claves

Los objetos de datos de Datastore se denominan entidades. Una entidad tiene una o varias propiedades con nombre, cada una de las cuales puede tener uno o varios valores. Las entidades del mismo tipo no tienen por qué tener las mismas propiedades, y los valores de una entidad para una propiedad determinada no tienen por qué ser todos del mismo tipo de datos. Si es necesario, una aplicación puede establecer y aplicar estas restricciones en su propio modelo de datos.

Datastore admite distintos tipos de datos para los valores de las propiedades. Entre ellos, se incluyen los siguientes:

• Números enteros
• Números de punto flotante
• Cadenas
• Fechas
• Datos binarios

Para ver una lista completa de los tipos, consulta Propiedades y tipos de valor.

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
• Un identificador de la entidad individual, que puede ser uno de los siguientes:
  • Una cadena key name
  • un ID numérico entero
• Una ruta de ancestro opcional que indica la ubicación de la entidad en la jerarquía de Datastore

Una aplicación puede obtener una entidad individual de Datastore mediante la clave de la entidad o puede recuperar una o varias entidades enviando una consulta basada en las claves o los valores de propiedad de las entidades.

El SDK de Go App Engine incluye un paquete para representar entidades de Datastore como estructuras de Go, así como para almacenarlas y recuperarlas en Datastore.

Datastore no aplica ninguna restricción a la estructura de las entidades, como si una propiedad determinada tiene un valor de un tipo concreto. Esta tarea se deja a la aplicación.

Tipos e identificadores

Cada entidad de Datastore es de un tipo concreto,que clasifica la entidad para las consultas. Por ejemplo, una aplicación de recursos humanos puede representar a cada empleado de una empresa con una entidad de tipo Employee. En la API Go Datastore, se especifica el tipo de una entidad al crear un datastore.Key. Todos los nombres de tipos que empiezan por dos guiones bajos (__) están reservados y no se pueden usar.

En el siguiente ejemplo se crea una entidad de tipo Employee, se rellenan los valores de sus propiedades y se guarda en Datastore:

import (
	"context"
	"time"

	"google.golang.org/appengine/datastore"
)

type Employee struct {
	FirstName          string
	LastName           string
	HireDate           time.Time
	AttendedHRTraining bool
}

func f(ctx context.Context) {
	// ...
	employee := &Employee{
		FirstName: "Antonio",
		LastName:  "Salieri",
		HireDate:  time.Now(),
	}
	employee.AttendedHRTraining = true

	key := datastore.NewIncompleteKey(ctx, "Employee", nil)
	if _, err := datastore.Put(ctx, key, employee); err != nil {
		// Handle err
	}
	// ...
}

El tipo Employee declara cuatro campos para el modelo de datos: FirstName, LastName, HireDate y AttendedHRTraining.

Además de un tipo, cada entidad tiene un identificador, que se asigna cuando se crea la entidad. Como forma parte de la clave de la entidad, el identificador se asocia de forma permanente a la entidad y no se puede cambiar. Se puede asignar de dos formas:

• Tu aplicación puede especificar su propia cadena nombre de clave para la entidad.
• Puedes hacer que Datastore asigne automáticamente a la entidad un ID numérico entero.

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

Datastore se puede configurar para generar 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.

Datastore genera una secuencia aleatoria de IDs no utilizados que se distribuyen de forma aproximadamente uniforme. Cada ID puede tener hasta 16 dígitos decimales.

Rutas de ancestros

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 superior:

// 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)

Transacciones y grupos de entidades

Cada intento de crear, actualizar o eliminar una entidad se lleva a cabo en el contexto de una transacción. Una sola transacción puede incluir cualquier número de estas operaciones. Para mantener la coherencia de los datos, la transacción asegura que todas las operaciones que contiene se apliquen a Datastore como una unidad o, si falla alguna de las operaciones, que no se aplique ninguna. Además, todas las lecturas con coherencia fuerte (consultas de ancestros o gets) que se realicen en la misma transacción observan una instantánea coherente de los datos.

Como hemos mencionado anteriormente, un grupo de entidades es un conjunto de entidades conectadas por ascendencia a un elemento raíz común. La organización de los datos en grupos de entidades puede limitar las transacciones que se pueden realizar:

• Todos los datos a los que accede una transacción deben estar incluidos en un máximo de 25 grupos de entidades.
• Si quiere usar consultas en una transacción, sus datos deben organizarse en grupos de entidades de forma que pueda especificar filtros de ancestros que coincidan con los datos correctos.
• Hay un límite de rendimiento de escritura de aproximadamente una transacción por segundo en un solo grupo de entidades. Esta limitación se debe a que Datastore realiza una replicación síncrona sin maestro de cada grupo de entidades en una zona geográfica amplia para ofrecer una alta fiabilidad y tolerancia a fallos.

En muchas aplicaciones, se puede usar la coherencia final (es decir, una consulta que no sea de ancestro y que abarque varios grupos de entidades, que a veces puede devolver datos ligeramente obsoletos) para obtener una visión general de datos no relacionados y, a continuación, usar la coherencia fuerte (una consulta de ancestro o un get de una sola entidad) para ver o editar un solo conjunto de datos muy relacionados. En estas aplicaciones, suele ser una buena estrategia usar un grupo de entidades independiente para cada conjunto de datos muy relacionados. Para obtener más información, consulta Estructurar datos para conseguir una coherencia inmediata.

Propiedades y tipos de valores

Los valores de datos asociados a una entidad constan de una o varias propiedades. Cada propiedad tiene un nombre y uno o varios valores. Una propiedad puede tener valores de más de un tipo, y dos entidades pueden tener valores de tipos diferentes para la misma propiedad. Las propiedades pueden estar indexadas o no (las consultas que ordenan o filtran por una propiedad P ignorarán las entidades en las que P no esté indexada). Una entidad puede tener como máximo 20.000 propiedades indexadas.

Se admiten los siguientes tipos de valores:

También puedes usar struct o slice para agregar propiedades. Consulta más información en la referencia de Datastore.

Cuando una consulta incluye una propiedad con valores de tipos mixtos, Datastore usa un orden determinista basado en las representaciones internas:

1. valores nulos
2. Números de coma fija
   • Números enteros
   • Fechas y horas
3. valores booleanos
4. Secuencias de bytes
   • Intervalos de bytes (corto)
   • Cadena Unicode
   • claves del almacén de blob
5. Números de punto flotante
6. Puntos geográficos
7. Claves de Datastore

Como no se indexan las porciones de bytes ni las cadenas largas, no tienen ningún orden definido.

Trabajar con entidades

Las aplicaciones pueden usar la API Datastore para crear, recuperar, actualizar y eliminar entidades. Si la aplicación conoce la clave completa de una entidad (o puede obtenerla a partir de su clave principal, su tipo y su identificador), puede usarla para operar directamente en la entidad. Una aplicación también puede obtener la clave de una entidad como resultado de una consulta de Datastore. Consulta la página Consultas de Datastore para obtener más información.

Crear una entidad

En Go, se crea una entidad construyendo una instancia de una estructura de Go, rellenando sus campos y llamando a datastore.Put para guardarla en Datastore. Solo se guardarán en Datastore los campos exportados (que empiezan por una letra mayúscula). Puedes especificar el nombre de la clave de la entidad pasando un argumento stringID no vacío a datastore.NewKey:

employee := &Employee{
	FirstName: "Antonio",
	LastName:  "Salieri",
	HireDate:  time.Now(),
}
employee.AttendedHRTraining = true
key := datastore.NewKey(ctx, "Employee", "asalieri", 0, nil)
_, err = datastore.Put(ctx, key, employee)

Si proporcionas un nombre de clave vacío o usas datastore.NewIncompleteKey, Datastore generará automáticamente un ID numérico para la clave de la entidad:

employee := &Employee{
	FirstName: "Antonio",
	LastName:  "Salieri",
	HireDate:  time.Now(),
}
employee.AttendedHRTraining = true
key := datastore.NewIncompleteKey(ctx, "Employee", nil)
_, err = datastore.Put(ctx, key, employee)

Recuperar una entidad

Para recuperar una entidad identificada por una clave determinada, pasa el *datastore.Key como argumento a la función datastore.Get. Puedes generar el *datastore.Key con la función datastore.NewKey.

employeeKey := datastore.NewKey(ctx, "Employee", "asalieri", 0, nil)
addressKey := datastore.NewKey(ctx, "Address", "", 1, employeeKey)
var addr Address
err = datastore.Get(ctx, addressKey, &addr)

datastore.Get rellena una instancia de la estructura Go adecuada.

Actualizar una entidad

Para actualizar una entidad, modifique los atributos de la estructura y, a continuación, llame a datastore.Put. Los datos sobrescriben la entidad. El objeto completo se envía a Datastore con cada llamada a datastore.Put.

Eliminar una entidad

Si tienes la clave de una entidad, puedes eliminarla con la función datastore.Delete:

key := datastore.NewKey(ctx, "Employee", "asalieri", 0, nil)
err = datastore.Delete(ctx, key)

Operaciones por lotes

datastore.Put, datastore.Get y datastore.Delete tienen variantes masivas llamadas datastore.PutMulti, datastore.GetMulti y datastore.DeleteMulti. Permiten actuar en varias entidades en una sola llamada de Datastore:

// A batch put.
_, err = datastore.PutMulti(ctx, []*datastore.Key{k1, k2, k3}, []interface{}{e1, e2, e3})

// A batch get.
var entities = make([]*T, 3)
err = datastore.GetMulti(ctx, []*datastore.Key{k1, k2, k3}, entities)

// A batch delete.
err = datastore.DeleteMulti(ctx, []*datastore.Key{k1, k2, k3})

Las operaciones por lotes no modifican tus costes. Se te cobrará por cada clave de una operación por lotes, independientemente de si existe o no. El tamaño de las entidades implicadas en una operación no afecta al coste.