allocateIds DatastoreService real-world usage

Question

Can I ask for some real world usages of the DatastoreService

 - allocateIdRange(KeyRange range)
 - allocateIds(Key parent, java.lang.String kind, long num)
 - allocateIds(java.lang.String kind, long num)

Answer 1

Uses of allocateIds():

1. You want to write several mutually referential entities in a transaction, using integer ids. You wouldn't know the "auto ids" (i.e., what you get if you leave the id/name of the key unset) until after you commit, so you couldn't make the entities "point to each other" (e.g. using reference properties) as part of the txn. But if you allocate some ids first, you can manually set the key ids to those you allocated, then write the mutually referential entities in a transaction, and without risk of collision with other auto ids.

2. You want user-facing ids that are human readable, e.g. for case numbers. The default auto ids are large numbers (~16 decimal digit), but allocateIds() gives you "old-style" sequential ids which will usually be much smaller (6 or 7 digits).

If the entity for which you wish to allocate ids has an ancestor, use the function that takes a parent Key arg. Else, use the other allocateIds where you just specify the kind.

As for allocateIdRange(), I would recommend you not use that. It was designed to allow you to reserve a block of the integer id space to do your own manual allocation, but this is difficult and inefficient to manage correctly on the client side, and is also no longer well supported (it will fail on the "new-style" large ids).