How do I interact with entities in Datastore?

dataset.save() seems to let me put some data, but how do I then get a hold of the persisted entity? Do we have documentation for this that I'm just missing?

@jgeewax

Yeah the entity is an object with key and data properties. When you run dataset#save you're actually just passing in an entity. When you dataset#get, datastore returns an array of entities that match your given query. We should perhaps create an Entity object with handy methods, as was discussed as potential in #508. In the meantime, I think documenting the entities returned from dataset#get a little better seems like a reasonable compromise. What do you think @jgeewax ?

I think an Entity class might be worthwhile... Can we write up some sample code of what this would look like and how we'd use it?

(Here's the Python documentation for this: http://googlecloudplatform.github.io/gcloud-python/latest/datastore-entities.html)

var entity = Entity(key: Key | String | Array, data: Object)

`key`

Required
Type: Key, String, Array

A pass-through to dataset.key if not already an instance of Key.

`data`

Required
Type: Object

entity.getKey()

Returns: Key

entity.getShouldExcludeFromIndexes();

Returns: Boolean

entity.shouldExcludeFromIndexes(Boolean);

Marks the entity as excluded from indexes.

Saving data

Old

var entity = {
  key: dataset.key('Company'),
  data: {
    HQ: 'Dallas, TX'
  },
  excludeFromIndexes: true
};

dataset.save(entity, callback);

New

var company = dataset.entity('Company', {
  HQ: 'Dallas, TX'
});
company.shouldExcludeFromIndexes();

dataset.save(entity, callback);

Getting data

Old

var companyKey = dataset.key(['Company', 123]);
dataset.get(companyKey, function(err, entity) {
  // entity.data.HQ === 'Dallas, TX';
});

New

var companyKey = dataset.key(['Company', 123]);
dataset.get(companyKey, function(err, entity) {
  // entity.HQ === 'Dallas, TX';
});

Getting the key after an operation

Old

var companyKey = dataset.key(['Company', 123]);
dataset.get(companyKey, function(err, entity) {
  // entity.key === companyKey;
});

New

var companyKey = dataset.key(['Company', 123]);
dataset.get(companyKey, function(err, entity) {
  // entity.getKey() === companyKey;
});

Notes

We can restrict users from creating Entity types, and instead only we would create and return them from the API calls. Currently, a user can sufficiently start any API call from just a Key instance. The only place Entity would be useful for a user to create is before a save, as our API now is a bit weird. But the weirdness of that might not be as weird as allowing users to create Entities and wonder:

"Does it have to be a complete key, or can I give it an incomplete key?"
"Do I have to set the data now?"
"Can I do a query with an entity? Or Key?"

Hope I didn't get the vision wrong!

What about the "get and modify" process. Would that look like....

var companyKey = dataset.key(['Company', 123]);
dataset.get(companyKey, function(err, entity) {
  entity.HQ = 'Houston, TX';
  dataset.save(entity);
});

?

Yes, that would work. Currently we have:

var companyKey = dataset.key(['Company', 123]);
dataset.get(companyKey, function(err, entity) {
  entity.data.HQ = 'Houston, TX';
  dataset.save(entity, callback);
});

I'm starting to wonder if an Entity type is a better solution than making sure we show more complete workflows in our Examples.

@callmehiphop

Anyone else have thoughts here? // @callmehiphop?

Looking at the old vs. new code samples, I don't really see any benefits in creating an Entity class. It sounds to me like our problem is that we need more documentation around interacting with entities. An Entity class could fix that, but I think it's the wrong way to go about it.

I agree. I like using plain JS objects where possible, and this seems like a logical place. I think #574 will go a long way to answer the question we repeatedly hear: "How do I get the generated ID?"

Regarding entities, users seem to be grasping how it works to store, get, and update. But, it couldn't hurt to add an example here: https://googlecloudplatform.github.io/gcloud-node/#/docs/v0.25.0/datastore/dataset?method=get