Esta página se ha traducido con Cloud Translation API.

Entidades, propiedades y claves

Los objetos de datos de Firestore en modo 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 del mismo tipo de datos. Si es necesario, una aplicación puede establecer y aplicar estas restricciones en su propio modelo de datos.

El modo Datastore admite varios 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

Cada entidad de una base de datos en el modo 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.
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 la base de datos.

Una aplicación puede obtener una entidad individual de la base de datos mediante la clave de la entidad, o bien puede recuperar una o varias entidades enviando una consulta basada en las claves o los valores de las propiedades de las entidades.

Firestore en el modo de 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.

Los fragmentos de código de esta página se basan en el ejemplo de la sección Primeros pasos con Firestore en modo Datastore.

Trabajar con entidades

Las aplicaciones pueden usar la API de Firestore en el modo de 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. Consulta el tema Consultas para obtener más información.

Crear una entidad

Para crear una entidad, inicialízala y define sus propiedades:

C#

Para saber cómo instalar y usar la biblioteca de cliente de Cloud Datastore, consulta las bibliotecas de cliente de Cloud Datastore. Para obtener más información, consulta la documentación de referencia de la API C# de Cloud Datastore.

Para autenticarte en Cloud Datastore, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["category"] = "Personal",
    ["done"] = false,
    ["priority"] = 4,
    ["description"] = "Learn Cloud Datastore"
};

Go

type Task struct {
	Category        string
	Done            bool
	Priority        float64
	Description     string `datastore:",noindex"`
	PercentComplete float64
	Created         time.Time
}
task := &Task{
	Category:        "Personal",
	Done:            false,
	Priority:        4,
	Description:     "Learn Cloud Datastore",
	PercentComplete: 10.0,
	Created:         time.Now(),
}

Java

Key taskKey = datastore.newKeyFactory().setKind("Task").newKey("sampleTask");
Entity task =
    Entity.newBuilder(taskKey)
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 4)
        .set("description", "Learn Cloud Datastore")
        .build();

Node.js

const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

PHP

$task = $datastore->entity('Task', [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

task = datastore.Entity(client.key("Task"))
task.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

Ruby

task = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

Puedes guardar la entidad en la base de datos mediante upsert (que sobrescribirá una entidad si ya existe en el modo Datastore) o insert (que requiere que la clave de la entidad no exista ya).

Para upsert una entidad, sigue estos pasos:

C#

_db.Upsert(_sampleTask);

Go

key := datastore.IncompleteKey("Task", nil)
key, err := client.Put(ctx, key, task)

Java

Entity task = Entity.newBuilder(keyFactory.newKey("sampleTask")).build();
datastore.put(task);

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

await datastore.upsert(entity);
// Task inserted successfully.

PHP

$key = $datastore->key('Task', 'sampleTask');
$task = $datastore->entity($key, [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);
$datastore->upsert($task);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

complete_key = client.key("Task", "sampleTask")

task = datastore.Entity(key=complete_key)

task.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

client.put(task)

Ruby

# task_name = "sampleTask"
task = datastore.entity "Task", task_name do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end
datastore.save task

Para insert una entidad, sigue estos pasos:

C#

Entity task = new Entity()
{
    Key = _keyFactory.CreateIncompleteKey()
};
task.Key = _db.Insert(task);

Go

taskKey := datastore.NameKey("Task", "sampleTask", nil)
_, err := client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
	// We first check that there is no entity stored with the given key.
	var empty Task
	if err := tx.Get(taskKey, &empty); err != datastore.ErrNoSuchEntity {
		return err
	}
	// If there was no matching entity, store it now.
	_, err := tx.Put(taskKey, &task)
	return err
})

Java

Key taskKey = datastore.add(FullEntity.newBuilder(keyFactory.newKey()).build()).getKey();

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

datastore.insert(entity).then(() => {
  // Task inserted successfully.
});

PHP

$task = $datastore->entity('Task', [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);
$datastore->insert($task);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

with client.transaction():
    incomplete_key = client.key("Task")

    task = datastore.Entity(key=incomplete_key)

    task.update(
        {
            "category": "Personal",
            "done": False,
            "priority": 4,
            "description": "Learn Cloud Datastore",
        }
    )

    client.put(task)

Ruby

datastore.transaction do |_tx|
  task = datastore.entity "Task" do |t|
    t["category"] = "Personal"
    t["done"] = false
    t["priority"] = 4
    t["description"] = "Learn Cloud Datastore"
  end
  datastore.save task
end

Recuperar una entidad

Para recuperar una entidad de la base de datos, usa su clave para buscarla:

C#

Entity task = _db.Lookup(_sampleTask.Key);

Go

var task Task
taskKey := datastore.NameKey("Task", "sampleTask", nil)
err := client.Get(ctx, taskKey, &task)

Java

Entity task = datastore.get(taskKey);

Node.js

const taskKey = datastore.key('Task');
const [entity] = await datastore.get(taskKey);
// entity = {
//   category: 'Personal',
//   done: false,
//   priority: 4,
//   description: 'Learn Cloud Datastore',
//   [Symbol(KEY)]:
//    Key {
//      namespace: undefined,
//      id: '...',
//      kind: 'Task',
//      path: [Getter]
//    }
//   }
// };
console.log(entity);

PHP

$task = $datastore->lookup($key);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")
task = client.get(key)

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name
task = datastore.find task_key

Actualizar una entidad

Para update una entidad, modifique las propiedades de la entidad que haya obtenido previamente y almacénela con la clave:

C#

_sampleTask["priority"] = 5;
_db.Update(_sampleTask);

Go

taskKey := datastore.NameKey("Task", "sampleTask", nil)
tx, err := client.NewTransaction(ctx)
if err != nil {
	log.Fatalf("client.NewTransaction: %v", err)
}
var task Task
if err := tx.Get(taskKey, &task); err != nil {
	log.Fatalf("tx.Get: %v", err)
}
task.Priority = 5
if _, err := tx.Put(taskKey, &task); err != nil {
	log.Fatalf("tx.Put: %v", err)
}
if _, err := tx.Commit(); err != nil {
	log.Fatalf("tx.Commit: %v", err)
}

Java

Entity task;
Transaction txn = datastore.newTransaction();
try {
  task = Entity.newBuilder(txn.get(taskKey)).set("priority", 5).build();
  txn.put(task);
  txn.commit();
} finally {
  if (txn.isActive()) {
    txn.rollback();
  }
}

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

await datastore.update(entity);
// Task updated successfully.

PHP

$transaction = $datastore->transaction();
$key = $datastore->key('Task', 'sampleTask');
$task = $transaction->lookup($key);
$task['priority'] = 5;
$transaction->update($task);
$transaction->commit();

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

with client.transaction():
    key = client.key("Task", "sampleTask")
    task = client.get(key)

    task["done"] = True

    client.put(task)

Ruby

# task_name = "sampleTask"
datastore.transaction do |_tx|
  task = datastore.find "Task", task_name
  task["priority"] = 5
  datastore.save task
end

Los datos proporcionados sobrescriben la entidad. Todo el objeto debe enviarse a la base de datos. Si la entidad no existe, no se podrá completar la actualización. Si quiere actualizar o crear una entidad, use upsert como se ha descrito anteriormente. Con una transacción, puedes realizar las operaciones get y update en una única transacción atómica.

Eliminar una entidad

Dada la clave de una entidad, puedes delete la entidad:

C#

_db.Delete(_sampleTask.Key);

Go

key := datastore.NameKey("Task", "sampletask", nil)
err := client.Delete(ctx, key)

Java

datastore.delete(taskKey);

Node.js

const taskKey = datastore.key('Task');
await datastore.delete(taskKey);
// Task deleted successfully.

PHP

$datastore->delete($taskKey);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")
client.delete(key)

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name
datastore.delete task_key

Operaciones por lotes

Firestore en el modo de Datastore admite versiones por lotes de las operaciones, lo que le permite operar en varios objetos en una sola llamada al modo de Datastore.

Estas llamadas por lotes son más rápidas que las llamadas independientes para cada entidad, ya que solo incurren en la sobrecarga de una llamada de servicio. Si hay varios grupos de entidades implicados, el trabajo de todos los grupos se realiza en paralelo en el lado del servidor.

Por ejemplo, puedes upsert varias entidades:

C#

var taskList = new[]
{
    new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["category"] = "Personal",
        ["done"] = false,
        ["priority"] = 4,
        ["description"] = "Learn Cloud Datastore"
    },
    new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["category"] = "Personal",
        ["done"] = "false",
        ["priority"] = 5,
        ["description"] = "Integrate Cloud Datastore"
    }
};
var keyList = _db.Upsert(taskList[0], taskList[1]);

Go

tasks := []*Task{
	{
		Category:    "Personal",
		Done:        false,
		Priority:    4,
		Description: "Learn Cloud Datastore",
	},
	{
		Category:    "Personal",
		Done:        false,
		Priority:    5,
		Description: "Integrate Cloud Datastore",
	},
}
keys := []*datastore.Key{
	datastore.IncompleteKey("Task", nil),
	datastore.IncompleteKey("Task", nil),
}

keys, err := client.PutMulti(ctx, keys, tasks)

Java

FullEntity<IncompleteKey> task1 =
    FullEntity.newBuilder(keyFactory.newKey())
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 4)
        .set("description", "Learn Cloud Datastore")
        .build();
FullEntity<IncompleteKey> task2 =
    Entity.newBuilder(keyFactory.newKey())
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 5)
        .set("description", "Integrate Cloud Datastore")
        .build();
List<Entity> tasks = datastore.add(task1, task2);
Key taskKey1 = tasks.get(0).getKey();
Key taskKey2 = tasks.get(1).getKey();

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const task1 = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const task2 = {
  category: 'Work',
  done: false,
  priority: 8,
  description: 'Integrate Cloud Datastore',
};

const entities = [
  {
    key: taskKey1,
    data: task1,
  },
  {
    key: taskKey2,
    data: task2,
  },
];

await datastore.upsert(entities);
// Tasks inserted successfully.

PHP

$result = $datastore->upsertBatch($tasks);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

task1 = datastore.Entity(client.key("Task", 1))

task1.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

task2 = datastore.Entity(client.key("Task", 2))

task2.update(
    {
        "category": "Work",
        "done": False,
        "priority": 8,
        "description": "Integrate Cloud Datastore",
    }
)

client.put_multi([task1, task2])

Ruby

task_1 = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

task_2 = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 5
  t["description"] = "Integrate Cloud Datastore"
end

tasks = datastore.save task_1, task_2
task_key_1 = tasks[0].key
task_key_2 = tasks[1].key

Puedes buscar varias entidades:

C#

var keys = new Key[] { _keyFactory.CreateKey(1), _keyFactory.CreateKey(2) };
var tasks = _db.Lookup(keys[0], keys[1]);

Go

var taskKeys []*datastore.Key // Populated with incomplete keys.
tasks := make([]*Task, len(taskKeys))
err := client.GetMulti(ctx, taskKeys, &tasks)

Java

Iterator<Entity> tasks = datastore.get(taskKey1, taskKey2);

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const keys = [taskKey1, taskKey2];

const [tasks] = await datastore.get(keys);
// Tasks retrieved successfully.
console.log(tasks);

PHP

$result = $datastore->lookupBatch($keys);
if (isset($result['found'])) {
    // $result['found'] is an array of entities.
} else {
    // No entities found.
}

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

keys = [client.key("Task", 1), client.key("Task", 2)]
tasks = client.get_multi(keys)

Ruby

# task_name_1 = "sampleTask1"
# task_name_2 = "sampleTask2"
task_key_1 = datastore.key "Task", task_name_1
task_key_2 = datastore.key "Task", task_name_2
tasks = datastore.find_all task_key_1, task_key_2

Puedes eliminar varias entidades:

C#

var keys = new Key[] { _keyFactory.CreateKey(1), _keyFactory.CreateKey(2) };
_db.Delete(keys);

Go

err := client.DeleteMulti(ctx, taskKeys)

Java

datastore.delete(taskKey1, taskKey2);

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const keys = [taskKey1, taskKey2];

await datastore.delete(keys);
// Tasks deleted successfully.

PHP

$result = $datastore->deleteBatch($keys);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

keys = [client.key("Task", 1), client.key("Task", 2)]
client.delete_multi(keys)

Ruby

# task_name_1 = "sampleTask1"
# task_name_2 = "sampleTask2"
task_key_1 = datastore.key "Task", task_name_1
task_key_2 = datastore.key "Task", task_name_2
datastore.delete task_key_1, task_key_2

Las operaciones por lotes no cambian los costes de lectura, escritura o eliminación, que se documentan en Precios y cuotas. 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 a los costes de lectura, escritura o eliminación. Sin embargo, el tamaño de las entidades sí influye en los costes de tamaño de almacenamiento.

Incremento y otras transformaciones de propiedades

Usa transformaciones de propiedades como increment para hacer cambios en una propiedad del lado del servidor. Una transformación de propiedad evita una operación de lectura adicional del lado del cliente para obtener el valor actual y evita un cálculo del lado del cliente para determinar el nuevo valor.

El modo Datastore admite las siguientes transformaciones de propiedades:

increment
maximum
minimum
appendMissingElements
removeAllFromArray
setToServerValue(REQUEST_TIME)

En el siguiente ejemplo se muestra una transformación de propiedad. Esta operación incrementa las propiedades en los valores especificados:

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "quantity",
          "increment": {
            "integerValue": 2
          }
        },
        {
          "property": "inStock",
          "maximum": {
            "integerValue": 100
          }
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Items",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

En el siguiente ejemplo, se asigna a una propiedad el valor de la hora en la que el servidor ha procesado la solicitud, con una precisión de milisegundos.

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "timeField",
          "setToServerValue": "REQUEST_TIME"
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

En el siguiente ejemplo se añaden elementos a un array si faltan.

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "arrayField",
          "appendMissingElements": {
            "values": [
              { "stringValue": "str" }, { "integerValue": 10 }
            ]
          }
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

Tipos mixtos con `maximum` y `minimum`

Las transformaciones de las propiedades maximum y minimum toman como entrada un número entero o un número de coma flotante. El valor de la propiedad target también puede ser un número entero o un valor doble.

Si la propiedad no es un número entero o de coma flotante, o si no existe, la transformación asigna a la propiedad el valor y el tipo de entrada proporcionados. Si se aplica una operación maximum en la que la propiedad y el valor de entrada son de tipos mixtos (es decir, uno es un entero y el otro es un número de coma flotante de doble precisión), la propiedad adopta el tipo del operando más grande. En el caso de minimum, la propiedad adopta el tipo del operando más pequeño.

Si los operandos son equivalentes (por ejemplo, 3 y 3,0), la propiedad no cambia. 0, 0,0 y -0,0 son todos cero. El maximum o el minimum de un valor almacenado cero y un valor de entrada cero siempre es el valor almacenado. El maximum o minimum de cualquier valor numérico y NaN es NaN.

Varias mutaciones y `PropertyMask`

Las transformaciones de propiedades se aplican secuencialmente después de cualquier otra mutación de la solicitud. Un PropertyMask restringe las mutaciones de insert, update y upsert a las propiedades especificadas, pero no restringe las transformaciones de propiedades.

Por ejemplo, si tenemos la siguiente entidad:

REST

entity: {
  "key" : {
    "path": [
      {
        "kind": "Kind_1",
        "name": "entity_1"
      }
    ]
  }
  "properties" : {
    "a": 1,
    "b": 2,
    "c": 3
  }
}

La siguiente solicitud actualiza a y b, y, a continuación, aplica una transformación de propiedad a la propiedad b:

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {"a", "b"},  // update property a, b
      "update": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
        "properties": {
          "a" : "new_value",
          "b" : -2
        }
      },
      "propertyTransforms": [
        {
          "property": "b",
          "increment": { 
            "integerValue": 2
          }
        }
      ]
    }
  ]
}

El resultado es el siguiente:

REST

entity: {
  "key" : {
    "path": [
      {
        "kind": "Kind_1",
        "name": "entity_1"
      }
    ]
  }
  "properties" : {
    "a": "new_value",
    "b": 0,
    "c": 3
  }
}

Tipos e identificadores

Cada entidad es de un tipo concreto, que clasifica la entidad para las consultas. Por ejemplo, una aplicación de lista de tareas podría representar cada tarea que se debe completar con una entidad de tipo Task.

Todos los nombres de tipos que empiezan por dos guiones bajos (__) están reservados y no se pueden usar.

Asignar identificadores

Además de un tipo, cada entidad tiene un identificador, que se le asigna cuando se crea. 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.

Para obtener información sobre el tamaño máximo de la cadena de clave de entidad, consulta Límites.
Puedes hacer que Firestore en el modo de Datastore asigne automáticamente a la entidad un ID numérico entero.
Para consultar las prácticas recomendadas sobre la asignación de identificadores, consulta la sección Claves de las prácticas recomendadas.

En el siguiente ejemplo se crea una clave de tipo Task que usa el nombre de clave "sampleTask" como identificador:

C#

Key key = _db.CreateKeyFactory("Task").CreateKey("sampleTask");

Go

taskKey := datastore.NameKey("Task", "sampletask", nil)

Java

Key taskKey = datastore.newKeyFactory().setKind("Task").newKey("sampleTask");

Node.js

const taskKey = datastore.key(['Task', 'sampleTask']);

PHP

$taskKey = $datastore->key('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name

El modo Datastore también puede asignar IDs automáticamente. El modo 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.

En el siguiente ejemplo se crea una clave con el tipo Task sin usar un nombre de clave. La clave completa (incluido el ID asignado automáticamente) de la entidad se devolverá cuando se guarde en el modo Datastore una entidad con la clave incompleta:

C#

Key incompleteKey = _db.CreateKeyFactory("Task").CreateIncompleteKey();
Key key = _db.AllocateId(incompleteKey);

Go

// A complete key is assigned to the entity when it is Put.
taskKey := datastore.IncompleteKey("Task", nil)

Java

KeyFactory keyFactory = datastore.newKeyFactory().setKind("Task");
Key taskKey = datastore.allocateId(keyFactory.newKey());

Node.js

const taskKey = datastore.key('Task');

PHP

$taskKey = $datastore->key('Task');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task")

Ruby

task_key = datastore.key "Task"

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

Asignar tu propio ID numérico

En lugar de usar cadenas de nombres de clave o generar IDs numéricos automáticamente, las aplicaciones avanzadas a veces pueden asignar manualmente sus propios IDs numéricos a las entidades que crean. Sin embargo, ten en cuenta que no hay nada que impida que una base de datos en modo 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 el método allocateIds().

El generador automático de IDs del modo Datastore registrará los IDs que se hayan asignado con estos métodos y evitará reutilizarlos para otra entidad, por lo que podrá usar estos IDs sin que haya conflictos. No puedes elegir manualmente los valores que devuelve el método allocateIds(). Los valores que devuelve allocateIds() los asigna el modo Datastore.

Rutas de ancestros

Las entidades de una base de datos en modo 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 su elemento superior. La nueva entidad es un elemento secundario de la entidad superior (ten en cuenta que, a diferencia de lo que ocurre en un sistema de archivos, la entidad superior 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. El modo 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).

Una entidad puede tener varios niveles de antecesores y descendientes. Los ancestros de una entidad son su superior, el superior de su superior y así sucesivamente de forma recursiva. Sus descendientes son sus elementos secundarios, los elementos secundarios de sus elementos secundarios y así sucesivamente. 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 concreta, 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 terminan con los de la propia entidad:

[User:alice, TaskList:default, Task:sampleTask]

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:

[User:alice]

Niveles de padres

Usa niveles de elementos principales para organizar los datos. Por ejemplo, si tu aplicación organiza entidades Task por entidades TaskList, usa un nivel de elemento superior:

C#

Key rootKey = _db.CreateKeyFactory("TaskList").CreateKey("default");
Key key = new KeyFactory(rootKey, "Task").CreateKey("sampleTask");

Go

parentKey := datastore.NameKey("TaskList", "default", nil)
taskKey := datastore.NameKey("Task", "sampleTask", parentKey)

Java

Key taskKey =
    datastore
        .newKeyFactory()
        .addAncestors(PathElement.of("TaskList", "default"))
        .setKind("Task")
        .newKey("sampleTask");

Node.js

const taskKey = datastore.key([
  'TaskList',
  'default',
  'Task',
  'sampleTask',
]);

PHP

$taskKey = $datastore->key('TaskList', 'default')
    ->pathElement('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("TaskList", "default", "Task", "sampleTask")
# Alternatively
parent_key = client.key("TaskList", "default")
key = client.key("Task", "sampleTask", parent=parent_key)

Ruby

# task_list_name = "default"
# task_name = "sampleTask"
task_key = datastore.key [["TaskList", task_list_name], ["Task", task_name]]

Si tu aplicación organiza las entidades Task primero por entidades User y, después, por entidades TaskList, usa varios niveles de elementos superiores:

C#

Key rootKey = _db.CreateKeyFactory("User").CreateKey("Alice");
Key taskListKey = new KeyFactory(rootKey, "TaskList").CreateKey("default");
Key key = new KeyFactory(taskListKey, "Task").CreateKey("sampleTask");

Go

userKey := datastore.NameKey("User", "alice", nil)
parentKey := datastore.NameKey("TaskList", "default", userKey)
taskKey := datastore.NameKey("Task", "sampleTask", parentKey)

Java

KeyFactory keyFactory =
    datastore
        .newKeyFactory()
        .addAncestors(PathElement.of("User", "Alice"), PathElement.of("TaskList", "default"))
        .setKind("Task");
Key taskKey = keyFactory.newKey("sampleTask");

Node.js

const taskKey = datastore.key([
  'User',
  'alice',
  'TaskList',
  'default',
  'Task',
  'sampleTask',
]);

PHP

$taskKey = $datastore->key('User', 'alice')
    ->pathElement('TaskList', 'default')
    ->pathElement('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("User", "alice", "TaskList", "default", "Task", "sampleTask")

Ruby

# user_name = "alice"
# task_list_name = "default"
# task_name = "sampleTask"
task_key = datastore.key([
                           ["User", user_name],
                           ["TaskList", task_list_name],
                           ["Task", task_name]
                         ])

Como se muestra en el ejemplo anterior, cuando creas una entidad con un elemento superior, debes especificar la ruta de ancestro completa del elemento superior.

Una aplicación que mantiene perfiles de usuario puede requerir solo un nivel de elemento principal para los datos del perfil de usuario. Por ejemplo, usa una ruta de ancestro User de un solo nivel para las entidades Profile:

[User:alice, Profile:public]

Una aplicación que ofrece la programación de salas de conferencias puede requerir varios niveles de elementos superiores, como una ruta de ancestro Building/Floor de varios niveles para entidades Room:

[Building:C, Floor:1, Room:123]

Grupos de entidades

Un grupo de entidades consta de una entidad raíz y todos sus descendientes. Las aplicaciones suelen usar grupos de entidades para organizar datos muy relacionados. Por ejemplo, una aplicación podría usar un grupo de entidades para almacenar datos sobre un producto o un perfil de usuario.

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. Una propiedad puede estar indexada o no (las consultas que ordenan o filtran por una propiedad p ignorarán las entidades en las que p no esté indexada).

Algunas propiedades de ejemplo:

C#

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["category"] = "Personal",
    ["created"] = new DateTime(1999, 01, 01, 0, 0, 0, DateTimeKind.Utc),
    ["done"] = false,
    ["priority"] = 4,
    ["percent_complete"] = 10.0,
    ["description"] = new Value()
    {
        StringValue = "Learn Cloud Datastore",
        ExcludeFromIndexes = true
    },
};

Go

type Task struct {
	Category        string
	Done            bool
	Priority        int
	Description     string `datastore:",noindex"`
	PercentComplete float64
	Created         time.Time
}
task := &Task{
	Category:        "Personal",
	Done:            false,
	Priority:        4,
	Description:     "Learn Cloud Datastore",
	PercentComplete: 10.0,
	Created:         time.Now(),
}

Java

Entity task =
    Entity.newBuilder(taskKey)
        .set("category", "Personal")
        .set("created", Timestamp.now())
        .set("done", false)
        .set("priority", 4)
        .set("percent_complete", 10.0)
        .set(
            "description",
            StringValue.newBuilder("Learn Cloud Datastore").setExcludeFromIndexes(true).build())
        .build();

Node.js

const task = [
  {
    name: 'category',
    value: 'Personal',
  },
  {
    name: 'created',
    value: new Date(),
  },
  {
    name: 'done',
    value: false,
  },
  {
    name: 'priority',
    value: 4,
  },
  {
    name: 'percent_complete',
    value: 10.0,
  },
  {
    name: 'description',
    value: 'Learn Cloud Datastore',
    excludeFromIndexes: true,
  },
];

PHP

$task = $datastore->entity(
    $key,
    [
        'category' => 'Personal',
        'created' => new DateTime(),
        'done' => false,
        'priority' => 4,
        'percent_complete' => 10.0,
        'description' => 'Learn Cloud Datastore'
    ],
    ['excludeFromIndexes' => ['description']]
);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

import datetime

key = client.key("Task")
task = datastore.Entity(key, exclude_from_indexes=("description",))
task.update(
    {
        "category": "Personal",
        "description": "Learn Cloud Datastore",
        "created": datetime.datetime.now(tz=datetime.timezone.utc),
        "done": False,
        "priority": 4,
        "percent_complete": 10.5,
    }
)
client.put(task)

Ruby

task = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["created"] = Time.now
  t["done"] = false
  t["priority"] = 4
  t["percent_complete"] = 10.0
  t["description"] = "Learn Cloud Datastore"
  t.exclude_from_indexes! "description", true
end

Propiedades de matriz

Una propiedad con más de un valor se denomina propiedad de matriz. Este ejemplo contiene dos propiedades de matriz. El primero se llama tags y tiene los valores fun y programming. El segundo se llama collaborators y tiene los valores alice y bob.

C#

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["collaborators"] = new ArrayValue() { Values = { "alice", "bob" } },
    ["tags"] = new ArrayValue() { Values = { "fun", "programming" } }
};

Go

type Task struct {
	Tags          []string
	Collaborators []string
}
task := &Task{
	Tags:          []string{"fun", "programming"},
	Collaborators: []string{"alice", "bob"},
}

Java

Entity task =
    Entity.newBuilder(taskKey)
        .set("tags", "fun", "programming")
        .set("collaborators", ListValue.of("alice", "bob"))
        .build();

Node.js

const task = {
  tags: ['fun', 'programming'],
  collaborators: ['alice', 'bob'],
};

PHP

$task = $datastore->entity(
    $key,
    [
        'tags' => ['fun', 'programming'],
        'collaborators' => ['alice', 'bob']
    ]
);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task")
task = datastore.Entity(key)
task.update({"tags": ["fun", "programming"], "collaborators": ["alice", "bob"]})

Ruby

# task_name = "sampleTask"
task = datastore.entity "Task", task_name do |t|
  t["tags"] = ["fun", "programming"]
  t["collaborators"] = ["alice", "bob"]
end

Las propiedades de matriz pueden ser útiles, por ejemplo, al realizar consultas con filtros de igualdad: una entidad cumple la consulta si alguno de sus valores de una propiedad coincide con el valor especificado en el filtro. Para obtener más información sobre las propiedades de matriz, incluidos los problemas que debes tener en cuenta, consulta el tema Consultas.

Tipos de valores admitidos

Las propiedades se almacenan como un mapa string/value que contiene los nombres y los valores de las propiedades de la entidad. Se admiten los siguientes tipos de valores:

Matriz

API REST
- Nombre del campo: arrayValue
- type: un objeto ArrayValue que contiene una matriz de objetos JSON Value
- Se puede asignar una propiedad de matriz mediante el campo arrayValue, que es del tipo ArrayValue, y asignando a su campo values una matriz de valores. Para que una propiedad no se indexe, asigna el valor true al campo excludeFromIndexes del objeto de valor de la propiedad.
API de RPC
- Nombre del campo: array_value
- type: un mensaje ArrayValue que contiene uno o varios mensajes Value
- Se puede asignar una propiedad de matriz mediante el campo array_value, que es del tipo ArrayValue, y rellenando su campo values con varios objetos Value. Para que una propiedad no se indexe, asigna el valor true al campo exclude_from_indexes de Value.
Orden: ninguno
Notas: No puede contener otro valor de array. La instancia de valor no debe definir meaning ni exclude_from_indexes.

Booleano

API REST
- Nombre del campo: booleanValue
- Tipo: true o false
API de RPC
- Nombre del campo: boolean_value
- type: bool
Orden: false<true

Blob

API REST
- Nombre del campo: blobValue
- type: string. Debe estar codificado en Base64.
API de RPC
- Nombre del campo: blob_value
- type: bytes
Orden: orden de bytes
Notas: Hasta 1500 bytes si la propiedad está indexada. De lo contrario, hasta 1.048.487 bytes (1 MiB - 89 bytes).

Fecha y hora

API REST
- Nombre del campo: timestampValue
- type: string (formato RFC 3339, con milisegundos; por ejemplo, 2013-05-14T00:01:00.234Z)
API de RPC
- Nombre del campo: timestamp_value
- type: Timestamp
Orden: cronológico
Notas:
- Cuando se almacenan en el modo Datastore, la precisión es de microsegundos. Cualquier precisión adicional se redondea a la baja.
- Cuando se devuelve como parte de una consulta de proyección, el modo Datastore convierte los valores de marca de tiempo en valores enteros de microsegundos.

Entidad insertada

API REST
- Nombre del campo: entityValue
- type: una entidad JSON
API de RPC
- Nombre del campo: entity_value
- tipo: un mensaje Entity
Orden: ninguno
Notas: Cuando se indexan, puedes hacer consultas sobre las subpropiedades. Si excluye este valor de la indexación, todas las subpropiedades también se excluirán de la indexación.

Número de punto flotante

API REST
- Nombre del campo: doubleValue
- type: number
API de RPC
- Nombre del campo: double_value
- type: double
Orden: numérico
Notas: doble precisión de 64 bits, IEEE 754

Punto geográfico

API REST
- Nombre del campo: geoPointValue
- type: un par de latitud y longitud en formato JSON
API de RPC
- Nombre del campo: geo_point_value
- tipo: un mensaje LatLng
Orden: por latitud y, a continuación, por longitud

Entero

API REST
- Nombre del campo: integerValue
- Tipo: número o cadena. Usa cadenas para los números enteros que no se puedan representar exactamente como números.
API de RPC
- Nombre del campo: integer_value
- type: int64
Orden: numérico

Clave

API REST
- Nombre del campo: keyValue
- type: una clave de modo Datastore JSON
API de RPC
- Nombre del campo: key_value
- tipo: un mensaje Key
Orden: por elementos de la ruta (tipo, identificador, tipo, identificador, etc.)

Nulo

API REST
- Nombre del campo: nullValue
- type: null
API de RPC
- Nombre del campo: null_value
- type: NullValue
Orden: ninguno

Cadena de texto

API REST
- Nombre del campo: stringValue
- type: cadena
API de RPC
- Nombre del campo: string_value
- type: string
Orden: orden de bytes codificado en UTF-8
Notas: Hasta 1500 bytes si la propiedad está indexada. De lo contrario, hasta 1.048.487 bytes (1 MiB - 89 bytes).

Ordenación de tipo de valor

Cuando una consulta incluye una propiedad con valores de tipos mixtos, una base de datos en modo Datastore usa un orden determinista basado en las representaciones internas. En la siguiente lista se muestra el orden:

valores nulos
Números de coma fija
- Números enteros
- Fechas y horas
valores booleanos
Cadenas de bytes
Cadenas Unicode
Números de punto flotante
Valores NaN
Puntos geográficos
Claves del modo Datastore

Entidades, propiedades y claves Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Trabajar con entidades

Crear una entidad

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

Recuperar una entidad

C#

Go

Java

Node.js

PHP

Python

Ruby

Actualizar una entidad

C#

Go

Java

Node.js

PHP

Python

Ruby

Eliminar una entidad

C#

Go

Java

Node.js

PHP

Python

Ruby

Operaciones por lotes

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

Incremento y otras transformaciones de propiedades

REST

REST

REST

Tipos mixtos con maximum y minimum

Varias mutaciones y PropertyMask

REST

REST

Tipos e identificadores

Asignar identificadores

Entidades, propiedades y claves

Tipos mixtos con `maximum` y `minimum`

Varias mutaciones y `PropertyMask`