func ExampleClient_PutMulti() {
	ctx := context.Background()
	client, _ := datastore.NewClient(ctx, "my-proj")
	// [START batch_upsert]
	tasks := []*Task{
		{
			Type:        "Personal",
			Done:        false,
			Priority:    4,
			Description: "Learn Cloud Datastore",
		},
		{
			Type:        "Personal",
			Done:        false,
			Priority:    5,
			Description: "Integrate Cloud Datastore",
		},
	}
	keys := []*datastore.Key{
		datastore.NewIncompleteKey(ctx, "Task", nil),
		datastore.NewIncompleteKey(ctx, "Task", nil),
	}

	keys, err := client.PutMulti(ctx, keys, tasks)
	// [END batch_upsert]
	_ = err  // Make sure you check err.
	_ = keys // keys now has the complete keys for the newly stored tasks.
}

// LogRunComplete logs the end of a completed (failed of finished) run of
// a coduno testrun
func LogRunComplete(pKey *datastore.Key, build *BuildData, in,
	out, extra string, exit error, prepLog string, stats syscall.Rusage) {
	tx, err := datastore.NewTransaction(ctx)
	if err != nil {
		fmt.Fprintf(os.Stderr, "LogRunComplete: Could not get transaction!")
	}
	build.EndTime = time.Now()
	if exit != nil {
		build.Status = "failed"
	} else {
		build.Status = "good"
	}
	_, err = tx.Put(pKey, build)
	if err != nil {
		fmt.Fprintf(os.Stderr, "LogRunComplete: Putting build failed!")
		tx.Rollback()
		return
	}
	data := &LogData{in, out, extra, prepLog, stats}
	k := datastore.NewIncompleteKey(ctx, buildKind, pKey)
	_, err = tx.Put(k, data)
	if err != nil {
		fmt.Fprintf(os.Stderr, "LogRunComplete: Putting data failed!")
		tx.Rollback()
		return
	}
	tx.Commit()
}

func ExampleNewIncompleteKey() {
	ctx := context.Background()
	// [START incomplete_key]
	taskKey := datastore.NewIncompleteKey(ctx, "Task", nil)
	// [END incomplete_key]
	_ = taskKey // Use the task key for datastore operations.
}

func ExamplePut() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		log.Fatal(err)
	}

	type Article struct {
		Title       string
		Description string
		Body        string `datastore:",noindex"`
		Author      *datastore.Key
		PublishedAt time.Time
	}
	newKey := datastore.NewIncompleteKey(ctx, "Article", nil)
	_, err = client.Put(ctx, newKey, &Article{
		Title:       "The title of the article",
		Description: "The description of the article...",
		Body:        "...",
		Author:      datastore.NewKey(ctx, "Author", "jbd", 0, nil),
		PublishedAt: time.Now(),
	})
	if err != nil {
		log.Fatal(err)
	}
}

// AddTask adds a task with the given description to the datastore,
// returning the key of the newly created entity.
func AddTask(ctx context.Context, client *datastore.Client, desc string) (*datastore.Key, error) {
	task := &Task{
		Desc:    desc,
		Created: time.Now(),
	}
	key := datastore.NewIncompleteKey(ctx, "Task", nil)
	return client.Put(ctx, key, task)
}

// AddBook saves a given book, assigning it a new ID.
func (db *datastoreDB) AddBook(b *Book) (id int64, err error) {
	ctx := context.Background()
	k := datastore.NewIncompleteKey(ctx, "Book", nil)
	k, err = db.client.Put(ctx, k, b)
	if err != nil {
		return 0, fmt.Errorf("datastoredb: could not put Book: %v", err)
	}
	return k.ID(), nil
}

// LogBuildStart sends info to the datastore, informing that a new build
// started
func LogBuildStart(challenge string, commit string, user string) (*datastore.Key, *BuildData) {
	key := datastore.NewIncompleteKey(ctx, buildKind, nil)
	build := &BuildData{challenge, user, commit, "started", time.Now(), time.Unix(0, 0)}

	key, err := datastore.Put(ctx, key, build)
	if err != nil {
		fmt.Fprintf(os.Stderr, "LogBuildStart: %v", err)
	}
	return key, build
}

// Save will put this AccessToken into Datastore using the given key.
func (x AccessToken) Save(ctx context.Context, key ...*datastore.Key) (*datastore.Key, error) {
	if len(key) > 1 {
		panic("zero or one key expected")
	}

	if len(key) == 1 && key[0] != nil {
		return datastore.Put(ctx, key[0], &x)
	}

	return datastore.Put(ctx, datastore.NewIncompleteKey(ctx, AccessTokenKind, nil), &x)
}

func ExampleClient_Put_upsert() {
	ctx := context.Background()
	client, _ := datastore.NewClient(ctx, "my-proj")
	task := &Task{} // Populated with appropriate data.
	key := datastore.NewIncompleteKey(ctx, "Task", nil)
	// [START upsert]
	key, err := client.Put(ctx, key, task)
	// [END upsert]
	_ = err // Make sure you check err.
	_ = key // key is the complete key for the newly stored task
}

func recordVisit(ctx context.Context, now time.Time, userIP string) error {
	v := &visit{
		Timestamp: now,
		UserIP:    userIP,
	}

	k := datastore.NewIncompleteKey(ctx, "Visit", nil)

	_, err := datastoreClient.Put(ctx, k, v)
	return err
}

// Put installs the Repository in the Client's datastore.
func (r *Repository) Put(c *Client) error {
	key := datastore.NewIncompleteKey(c.ctx, repositoryKind, nil)

	key, err := c.datastore.Put(c.ctx, key, r)
	if err != nil {
		return err
	}

	r.key = key

	return nil
}

func example() {
	// [START master_slave_data_definition_code]
	g := Greeting{ /* ... */ }
	key := datastore.NewIncompleteKey(ctx, "Greeting", nil)
	// [END master_slave_data_definition_code]

	// [START master_slave_query_code]
	q := datastore.NewQuery("Greeting").Order("-Date").Limit(10)
	// [END master_slave_query_code]

	_ = g
	_ = key
	_ = q
}

func example2() {
	// [START high_replication_data_definition_code]
	g := Greeting{ /* ... */ }
	key := datastore.NewIncompleteKey(ctx, "Greeting", guestbookKey(ctx))
	// [END high_replication_data_definition_code]

	// [START high_replication_query_code]
	q := datastore.NewQuery("Greeting").Ancestor(guestbookKey(ctx)).Order("-Date").Limit(10)
	// [END high_replication_query_code]

	_ = g
	_ = key
	_ = q
}

func ExampleClient_Put() {
	ctx := context.Background()
	client, _ := datastore.NewClient(ctx, "my-proj")
	// [START entity_with_parent]
	parentKey := datastore.NewKey(ctx, "TaskList", "default", 0, nil)
	key := datastore.NewIncompleteKey(ctx, "Task", parentKey)

	task := Task{
		Type:        "Personal",
		Done:        false,
		Priority:    4,
		Description: "Learn Cloud Datastore",
	}

	// A complete key is assigned to the entity when it is Put.
	var err error
	key, err = client.Put(ctx, key, &task)
	// [END entity_with_parent]
	_ = err // Make sure you check err.
}

func putAuthorizedKey(ak *AuthorizedKey, username string) (err error) {
	ctx, err := connect()
	if err != nil {
		return
	}

	var coder Coder
	it := datastore.NewQuery(coderKind).Filter("Nickname =", username).Limit(1).Run(ctx)
	ck, err := it.Next(&coder)
	if err != nil {
		return
	}

	ak.Coder = ck

	dk := datastore.NewIncompleteKey(ctx, keyKind, nil)
	_, err = datastore.Put(ctx, dk, ak)

	return
}

func (fe *FeServiceImpl) AddBiosphere(ctx context.Context, q *api.AddBiosphereQ) (*api.AddBiosphereS, error) {
	ctx = TraceStart(ctx, "/frontend.AddBiosphere")
	defer TraceEnd(ctx, fe.ServerCred)

	if q.Auth == nil {
		return nil, errors.New("AddBiosphere requires auth")
	}
	canWrite, err := fe.isWriteAuthorized(ctx, q.Auth)
	if err != nil {
		return nil, err
	}
	if !canWrite {
		return nil, errors.New("UI must disallow unauthorized actions")
	}

	client, err := fe.AuthDatastore(ctx)
	if err != nil {
		return nil, err
	}

	valid, err := fe.isValidNewConfig(ctx, client, q.Config)
	if err != nil {
		return nil, err
	}
	if !valid || q.TestOnly {
		return &api.AddBiosphereS{Success: valid}, nil
	}

	envBlob, err := proto.Marshal(q.Config.Env)
	if err != nil {
		return nil, err
	}
	key := datastore.NewIncompleteKey(ctx, "BiosphereMeta", nil)
	meta := &BiosphereMeta{
		Name: q.Config.Name,
		Nx:   q.Config.Nx,
		Ny:   q.Config.Ny,
		Env:  envBlob,
	}
	key, err = client.Put(ctx, key, meta)
	if err != nil {
		return nil, err
	}

	if q.Config.Env.StorageFileId != "" {
		bsTopo := NewCylinderTopology(uint64(key.ID()), int(meta.Nx), int(meta.Ny))
		err = fe.expandStorageToSnapshot(ctx, bsTopo, q.Config.Env.StorageFileId)
		if err != nil {
			log.Printf("ERROR: Failed to initialize with snapshot %v", err)
			log.Printf("Deleting biosphere entry %v", key)
			dsErr := client.Delete(ctx, key)
			if dsErr != nil {
				log.Printf("ERROR: Failed to delete BiosphereMeta(%v); datastore might have become inconsistent", key)
			}
			return nil, err
		}
	}

	return &api.AddBiosphereS{
		Success: true,
		BiosphereDesc: &api.BiosphereDesc{
			BiosphereId: uint64(key.ID()),
			Name:        meta.Name,
			NumCores:    uint32(meta.Nx*meta.Ny/5) + 1,
		},
	}, nil
}

// SaveWithParent can be used to save this AccessToken as child of another
// entity.
// This will error if parent == nil.
func (x AccessToken) SaveWithParent(ctx context.Context, parent *datastore.Key) (*datastore.Key, error) {
	if parent == nil {
		return nil, errors.New("parent key is nil, expected a valid key")
	}
	return datastore.Put(ctx, datastore.NewIncompleteKey(ctx, AccessTokenKind, parent), &x)
}

// Reads storage file (binary proto of ChunkSnapshot) and copies it as snapshots
// of multiple chunks.
func (fe *FeServiceImpl) expandStorageToSnapshot(ctx context.Context, bsTopo BiosphereTopology, objectName string) error {
	ctx = TraceStart(ctx, "/frontend._.getStorage")
	defer TraceEnd(ctx, fe.ServerCred)

	service, err := fe.AuthStorage(ctx)

	res, err := service.Objects.Get(InitialEnvBucket, objectName).Download()
	if err != nil {
		log.Printf("WARNING: Failed to retrieve cloud storage object containing initial env, %v", err)
		return err
	}
	defer res.Body.Close()
	blob, err := ioutil.ReadAll(res.Body)
	if err != nil {
		log.Printf("ERROR: Failed to download storage %v", err)
		return err
	}
	snapshot := &api.ChunkSnapshot{}
	err = proto.Unmarshal(blob, snapshot)
	if err != nil {
		log.Printf("ERROR: Failed to unmarshal snapshot proto %v", err)
		return err
	}

	// Bin grains.
	type ChunkKey struct {
		ix, iy int
	}
	bins := make(map[ChunkKey][]*api.Grain)
	for _, grain := range snapshot.Grains {
		key := ChunkKey{int(grain.Pos.X), int(grain.Pos.Y)}
		localGrain := proto.Clone(grain).(*api.Grain)
		localGrain.Pos.X -= float32(key.ix)
		localGrain.Pos.Y -= float32(key.iy)
		bins[key] = append(bins[key], localGrain)
	}

	dsClient, err := fe.AuthDatastore(ctx)
	if err != nil {
		return err
	}

	// Convert to chunk snapshots and write them.
	offsets := bsTopo.GetGlobalOffsets()
	for _, chunk := range bsTopo.GetChunkTopos() {
		offset := offsets[chunk.ChunkId]
		key := ChunkKey{int(offset.X), int(offset.Y)}
		// We need to create snapshot even though 0 grains is contained.
		chunkSnapshot := &api.ChunkSnapshot{
			Grains: bins[key],
		}
		chunkBlob, err := proto.Marshal(chunkSnapshot)
		if err != nil {
			log.Printf("ERROR: Failed to marshal chunk snapshot proto %v", err)
			return err
		}

		// TODO: use transaction.
		dsKey := datastore.NewIncompleteKey(ctx, "PersistentChunkSnapshot", nil)
		_, err = func(ctx context.Context) (*datastore.Key, error) {
			ctx = TraceStart(ctx, "/google/datastore.Put")
			defer TraceEnd(ctx, fe.ServerCred)
			return dsClient.Put(ctx, dsKey, &PersistentChunkSnapshot{
				ChunkId:   chunk.ChunkId,
				Timestamp: 0,
				Snapshot:  chunkBlob,
			})
		}(ctx)
		if err != nil {
			log.Printf("ERROR: Failed to write chunk snapshot %v; snapshot became inconsistent", err)
			return err
		}
	}
	return nil
}

func (ds *Datastore) getIKey(i x.Instruction, tablePrefix string) *datastore.Key {
	skey := datastore.NewKey(ds.ctx, tablePrefix+"Entity", i.SubjectId, 0, nil)
	return datastore.NewIncompleteKey(ds.ctx, tablePrefix+"Instruction", skey)
}

// PutRepository uploads the described repository, and all of its files in dir.
func (c *Client) PutRepository(r *Repository, dir string) error {
	// Install the repository, so we can get its key.
	if err := r.Put(c); err != nil {
		return err
	}

	dir = filepath.Clean(dir)

	// Upload all files to GCS and install their datastore entries.
	return filepath.Walk(dir, func(localPath string, info os.FileInfo, err error) error {
		log.Printf("Processing %q", localPath)
		defer log.Printf("Finished %q", localPath)

		if err != nil {
			// We don't even try to deal with errors.
			return err
		}

		if info.IsDir() {
			// We only need to upload real files.
			return nil
		}

		src, err := os.Open(localPath)
		if err != nil {
			return err
		}

		// We upload the file under the r.Root path.
		rel, err := filepath.Rel(dir, localPath)
		if err != nil {
			return err
		}
		name := path.Join(r.Root, rel)

		dst := gcs.NewWriter(c.ctx, c.bucket, name)

		if _, err := io.Copy(dst, src); err != nil {
			// CloseWithError always returns nil.
			dst.CloseWithError(err)
			return err
		}

		if err := dst.Close(); err != nil {
			return err
		}

		// Describe the file in datastore.
		file := &File{
			Repository: r.key,
			Bucket:     c.bucket,
			Path:       name,
		}
		fileKey := datastore.NewIncompleteKey(c.ctx, fileKind, nil)
		if _, err := c.datastore.Put(c.ctx, fileKey, file); err != nil {
			return err
		}

		return nil
	})
}