Entidades, propiedades y claves

Los objetos de datos en Datastore se conocen como entidades. Una entidad posee una o más propiedades con nombre, que pueden tener uno o más valores. No es necesario que las entidades del mismo tipo tengan las mismas propiedades, ni que los valores de una entidad para una propiedad determinada correspondan al mismo tipo de datos. (Si fuera necesario, una aplicación puede establecer y aplicar estas restricciones en su propio modelo de datos).

Datastore es compatible con una variedad de tipos de datos para valores de propiedad. Se incluyen, entre otros:

  • Números enteros
  • números de punto flotante
  • Strings
  • Fechas
  • Datos binarios

Para obtener una lista completa de los tipos, consulta Tipos de valores y propiedades.

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

  • El espacio de nombres de la entidad, que permite la función de multiusuario
  • El tipo de entidad, que la clasifica para realizar consultas de Datastore
  • Un identificador de la entidad individual, que puede ser de alguna de las siguientes clases:
    • Una string de nombre de clave
    • un ID numérico entero
  • Una ruta principal opcional que ubica la entidad dentro de la jerarquía de Datastore

Una aplicación puede recuperar una entidad individual de Datastore mediante la clave de la entidad, o una o más entidades si emite una consulta basada en los valores de propiedad o las claves de las entidades.

El SDK de Go para App Engine incluye un paquete que representa las entidades de Datastore como estructuras de Go, con el fin de almacenarlas y recuperarlas en Datastore.

Datastore no aplica ninguna restricción en las estructuras de las entidades. Por ejemplo, si una propiedad posee un valor de un tipo en particular, esta tarea le corresponde a la aplicación.

Identificadores y tipos

Cada entidad de Datastore es de un tipo en particular que clasifica la entidad para realizar consultas; por ejemplo, una aplicación de recursos humanos podría representar a cada empleado de una empresa mediante una entidad del tipo Employee. En la API de Go para Datastore, debes especificar un tipo de entidad cuando crees una datastore.Key. Todos los nombres de tipo que comienzan con dos guiones bajos (__) están reservados y no se pueden usar.

En el siguiente ejemplo, se crea una entidad de tipo Employee, se propagan sus valores de propiedad y se la 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.

Cada entidad, además de un tipo, también posee un identificador, que se le asigna cuando se la crea. Debido a que es parte de la clave de la entidad, el identificador se encuentra asociado de forma permanente a la entidad y no se puede cambiar. Se puede asignar de dos maneras:

  • Tu aplicación puede especificar su propia string de nombre de clave para la entidad.
  • Puedes hacer que Datastore asigne de forma automática un ID de número entero a la entidad.

Para asignar un nombre de clave a la entidad, proporciona un argumento stringID no 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 de forma automática, 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)

Asigna identificadores

Datastore se puede configurar para generar ID de forma automática mediante dos políticas de identificación automática diferentes:

  • La política default genera una secuencia aleatoria de ID sin usar con una distribución bastante uniforme. Cada ID puede tener hasta 16 dígitos decimales.
  • La política legacy crea una secuencia de ID de números enteros no consecutivos más breves.

Si quieres mostrar al usuario los ID de la entidad o depender de su pedido, lo mejor que puedes hacer es usar la asignación manual.

Datastore genera una secuencia aleatoria de ID sin usar con una distribución bastante uniforme. Cada ID puede tener hasta 16 dígitos decimales.

Rutas de principales

Las entidades de Cloud Datastore conforman un espacio con estructura jerárquica, similar a la estructura de directorios de un sistema de archivos. Cuando creas una entidad, tienes la opción de designar otra entidad como superior, en cuyo caso la nueva entidad es secundaria respecto de la entidad superior (ten en cuenta que, a diferencia de lo que ocurre en un sistema de archivos, no es necesario que efectivamente exista una entidad superior). Las entidades que no tienen una principal se denominan entidades raíz. La asociación entre una entidad secundaria y la entidad superior es permanente, y no puede cambiarse una vez creada la entidad. Cloud Datastore nunca asignará el mismo ID numérico a dos entidades asociadas a la misma entidad superior ni a dos entidades raíz (no asociadas a una entidad superior).

La entidad superior de una entidad determinada, la superior de la superior y así sucesivamente son sus principales. Las entidades secundarias respecto de una entidad determinada, las secundarias de las secundarias y así sucesivamente son sus descendientes. Una entidad raíz y todos sus descendientes pertenecen al mismo grupo de entidad. La secuencia de entidades que comienza con una entidad raíz y sigue de principal a secundaria, hasta llegar a una entidad determinada, constituye la ruta de principal de esa entidad. La clave completa que identifica una entidad consta de una secuencia de pares de tipo-identificador que especifican la ruta de principales y terminan con el tipo y el identificador de la propia entidad:

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

En el caso de una entidad raíz, la ruta de principales está vacía, y la clave consta solo del tipo y el identificador de la entidad:

[Person:GreatGrandpa]

Este concepto se ilustra en el diagrama siguiente:

Muestra la relación de la entidad raíz con las entidades secundarias del grupo de entidad

Para designar el superior de una entidad, usa el argumento parent en datastore.NewKey. El valor de este argumento debería 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 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 borrar una entidad ocurre en el contexto de una transacción. Una transacción puede incluir una cantidad indeterminada de las operaciones mencionadas. Para conservar la coherencia de los datos, la transacción garantiza que todas las operaciones que contiene se apliquen a Datastore como una unidad o, si alguna de ellas falla, que no se aplique ninguna. Además, todas las operaciones de lectura de coherencia sólida (consultas principales o get) que se realizan dentro de la misma transacción ven una sola instantánea coherente de los datos.

Como se mencionó antes, un grupo de entidades es un conjunto de entidades conectadas de manera ascendente 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 contenidos en 25 grupos de entidades como máximo.
  • Si quieres usar consultas dentro de una transacción, los datos deben estar organizados en grupos de entidades de manera tal que puedas especificar filtros de principales que coincidan con los datos correctos.
  • Existe un límite de capacidad de procesamiento de escrituras de alrededor de una transacción por segundo dentro de un mismo grupo de entidades. Esta limitación existe porque Datastore realiza una replicación síncrona sin instancia maestra de cada grupo de entidades en un área geográfica amplia para brindar alta confiabilidad y tolerancia a errores.

En muchas aplicaciones, es aceptable usar la coherencia eventual (es decir, una consulta no principal que abarque varios grupos de entidades y que a veces puede mostrar datos ligeramente inactivos) cuando se obtiene una vista amplia de datos no relacionados y, luego, usar la coherencia sólida (una consulta principal o una get de una sola entidad) cuando se visualiza o edita un solo conjunto de datos muy relacionados. En tales aplicaciones, suele ser una buena estrategia usar un grupo de entidades separado para cada conjunto de datos sumamente relacionados. Si deseas obtener más información, consulta Estructura datos para lograr una coherencia sólida.

Tipos de valores y propiedades

Los valores de datos asociados con una entidad constan de una o más propiedades. Cada propiedad tiene un nombre y uno o más valores. Una propiedad puede tener valores de más de un tipo, y dos entidades pueden tener valores de diferentes tipos para la misma propiedad. Las propiedades pueden o no estar indexadas (las consultas que ordenan o filtran en 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 tipos de valor siguientes:

Tipo de valor Tipos de Go Orden de clasificación Notas
Número entero int
int8
int16
int32
int64
Numérico Número entero de 64 bits, con firma
Número de coma flotante float32
float64
Numérico Precisión doble de 64 bits,
IEEE 754
Booleano bool false<true
String (corta) string Unicode
Hasta 1,500 bytes. Los valores más largos que 1,500 bytes dan como resultado un error en el entorno de ejecución.
String (larga) string (con noindex) Ninguno Hasta 1 megabyte

Sin indexar
Segmento de bytes (corto) datastore.ByteString Orden de bytes Hasta 1,500 bytes. Los valores más largos que 1,500 bytes dan como resultado un error en el entorno de ejecución.
Segmento de bytes (largo) []byte Ninguno Hasta 1 megabyte

Sin indexar
Fecha y hora time.Time Cronológico
Punto geográfico appengine.GeoPoint Por latitud,
luego por longitud
Clave de Datastore *datastore.Key Por elementos de ruta de acceso
(tipo, identificador,
tipo, identificador…)
Clave de Blobstore appengine.BlobKey Orden de bytes

También puedes usar struct o slice para agregar propiedades. Para obtener más detalles, consulta la referencia de Datastore.

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

  1. Valores nulos
  2. Números de coma fija
    • Números enteros
    • fechas y horarios
  3. Valores booleanos
  4. Secuencias de bytes
    • Segmentos de bytes (cortos)
    • string de Unicode
    • Claves de Blobstore
  5. Números de coma flotante
  6. Puntos geográficos
  7. Claves de Datastore

Debido a que los segmentos de bytes largos y las strings largas no se indexan, no tienen un orden definido.

Trabaja con entidades

Las aplicaciones pueden usar la API de Datastore para crear, recuperar, actualizar y borrar entidades. Si la aplicación conoce la clave completa de una entidad (o puede obtenerla del tipo, identificador o clave de la superior), puede usar la clave para operar directamente con la entidad. Una aplicación también puede obtener la clave de una entidad como resultado de una consulta de Datastore. Visita la página Consultas de Datastore para obtener más información.

Cómo crear una entidad

En Go, para crear una entidad nueva debes construir una instancia de una estructura de Go, propagar sus campos y llamar a datastore.Put a fin de guardarla en Datastore. Solo se guardarán en Datastore los campos exportados (que empiecen con una letra mayúscula). Puede especificar el nombre de clave de la entidad si pasas 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)

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

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

Cómo recuperar una entidad

Para recuperar una entidad identificada mediante una clave determinada, pasa *datastore.Key como un argumento a la función datastore.Get. Puedes generar la *datastore.Key mediante 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 propaga una instancia de la estructura de Go adecuada.

Cómo actualizar una entidad

Para actualizar una entidad existente, modifica los atributos de la estructura y, luego, llama a datastore.Put. Los datos reemplazan la entidad existente. El objeto completo se envía a Datastore con cada llamada a datastore.Put.

Cómo borrar una entidad

Si tienes la clave correspondiente, puedes borrar una entidad 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 a 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 afectan los costos. Se te cobrará por cada clave de una operación por lotes, independientemente de si la clave existe o no. El tamaño de las entidades involucradas en una operación no afecta el costo.