Como criar, recuperar, atualizar e excluir entidades

Os objetos de dados no Datastore são conhecidos como entidades. Cada uma é categorizada como um tipo específico para fins de consultas. Por exemplo, se você estiver programando um aplicativo de recursos humanos, poderá representar cada funcionário com uma entidade do tipo Employee. Observe que os valores de dados de entidade estão na forma de propriedades. Para mais informações sobre entidades, consulte o documento conceitual Entidades, propriedades e chaves.

Como criar entidades e definir propriedades

Para criar uma nova entidade no Go, gere uma instância de estrutura do Go preenchendo os campos dela e chamando datastore.Put para salvá-la no Datastore. Apenas os campos exportados (que começam com uma letra maiúscula) serão salvos no Datastore. É possível especificar o nome de chave da entidade transmitindo um argumento stringID não vazio para datastore.NewKey.

O exemplo a seguir cria uma entidade do tipo Employee, preenche os valores da propriedade e a salva no 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
	}
	// ...
}

O tipo Employee declara quatro campos para o modelo de dados: FirstName, LastName, HireDate e AttendedHRTraining.

Se você fornecer um nome de chave vazio ou usar datastore.NewIncompleteKey, o Datastore gerará automaticamente um ID numérico para a chave da entidade:

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

Como recuperar entidades

Para recuperar uma entidade identificada por uma determinada chave, transmita o *datastore.Key como um argumento para a função datastore.Get. É possível gerar o *datastore.Key usando a função 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)

O datastore.Get preenche uma instância da estrutura do Go apropriada.

Como atualizar entidades

Para atualizar uma entidade atual, modifique os atributos da estrutura e, em seguida, chame datastore.Put. Os dados substituem a entidade existente. O objeto inteiro é enviado ao Datastore com todas as chamadas para datastore.Put.

Como excluir entidades

Dada a chave de uma entidade, é possível excluir a entidade com a função datastore.Delete:

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

Como excluir entidades em massa

Se você precisar excluir um grande número de entidades, recomendamos usar o Dataflow para excluir entidades em massa.

Como usar operações em lote

Use as operações em lote a seguir se quiser operar em várias entidades em uma única chamada do Datastore:

Veja um exemplo de chamada em lote:

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

As operações em lote não alteram os custos. Você será cobrado por todas as chaves em uma operação em lote, independentemente de cada chave existir ou não. O tamanho das entidades envolvidas em uma operação não afeta o custo.