Handle logic for Datastore API operations. Handles request logic for Datastore.
Creates requests to the Datastore endpoint. Designed to be inherited by the Datastore and Transaction classes.
Package
@google-cloud/datastoreProperties
datastore
datastore
:
Datastore
;
id
id
:
string
|
undefined
;
requestCallbacks_
requestCallbacks_
:
Array
< (
err
:
Error
|
null
,
resp
:
Entity
|
null
)
=
>
void
>
|
Entity
;
requests_
requests_
:
Entity
|
{
mutations
:
Array
< {}>;
};
Methods
allocateIds(key, options)
allocateIds
(
key
:
entity
.
Key
,
options
:
AllocateIdsOptions
|
number
)
:
Promise<AllocateIdsResponse>
;
Generate IDs without creating entities.
Parameters
Name
Description
key
options
AllocateIdsOptions
| number
Either the number of IDs to allocate or an options object for further customization of the request.
Returns
Type
Description
Promise
< AllocateIdsResponse
>
const
incompleteKey
=
datastore
.
key
([
'Company'
]);
//-
// The following call will create 100 new IDs from the Company kind, which
// exists under the default namespace.
//-
datastore
.
allocateIds
(
incompleteKey
,
100
,
(
err
,
keys
)
=
>
{});
//-
// Or, if you're using a transaction object.
//-
const
transaction
=
datastore
.
transaction
();
transaction
.
run
((
err
)
=
>
{
if
(
err
)
{
// Error handling omitted.
}
transaction
.
allocateIds
(
incompleteKey
,
100
,
(
err
,
keys
)
=
>
{
if
(
err
)
{
// Error handling omitted.
}
transaction
.
commit
((
err
)
=
>
{
if
(
!
err
)
{
// Transaction committed successfully.
}
});
});
});
//-
// You may prefer to create IDs from a non-default namespace by providing
an
// incomplete key with a namespace. Similar to the previous example, the
call
// below will create 100 new IDs, but from the Company kind that exists
under
// the "ns-test" namespace.
//-
const
incompleteKey
=
datastore
.
key
({
namespace
:
'ns-test'
,
path
:
[
'Company'
]
});
function
callback
(
err
,
keys
,
apiResponse
)
{}
datastore
.
allocateIds
(
incompleteKey
,
100
,
callback
);
//-
// Returns a Promise if callback is omitted.
//-
datastore
.
allocateIds
(
incompleteKey
,
100
).
then
((
data
)
=
>
{
const
keys
=
data
[
0
];
const
apiResponse
=
data
[
1
];
});
allocateIds(key, options, callback)
allocateIds
(
key
:
entity
.
Key
,
options
:
AllocateIdsOptions
|
number
,
callback
:
AllocateIdsCallback
)
:
void
;
Parameters
Name
Description
key
options
AllocateIdsOptions
| number
callback
AllocateIdsCallback
Returns
Type
Description
void
createReadStream(keys, options)
createReadStream
(
keys
:
Entities
,
options
?:
CreateReadStreamOptions
)
:
Transform
;
Retrieve the entities as a readable object stream.
Parameters
Name
Description
keys
Entities
Datastore key object(s).
options
CreateReadStreamOptions
Optional configuration. See for a complete list of options.
Returns
Type
Description
Transform
const
keys
=
[
datastore
.
key
([
'Company'
,
123
]),
datastore
.
key
([
'Product'
,
'Computer'
])
];
datastore
.
createReadStream
(
keys
)
.
on
(
'error'
,
(
err
)
=
>
{})
.
on
(
'data'
,
(
entity
)
=
>
{
// entity is an entity object.
})
.
on
(
'end'
,
()
=
>
{
// All entities retrieved.
});
delete(keys, gaxOptions)
delete
(
keys
:
Entities
,
gaxOptions
?:
CallOptions
)
:
Promise<DeleteResponse>
;
Delete all entities identified with the specified key(s).
Parameters
Name
Description
keys
Entities
gaxOptions
CallOptions
Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
Returns
Type
Description
Promise
< DeleteResponse
>
const
key
=
datastore
.
key
([
'Company'
,
123
]);
datastore
.
delete
(
key
,
(
err
,
apiResp
)
=
>
{});
//-
// Or, if you're using a transaction object.
//-
const
transaction
=
datastore
.
transaction
();
transaction
.
run
((
err
)
=
>
{
if
(
err
)
{
// Error handling omitted.
}
transaction
.
delete
(
key
);
transaction
.
commit
((
err
)
=
>
{
if
(
!
err
)
{
// Transaction committed successfully.
}
});
});
//-
// Delete multiple entities at once.
//-
datastore
.
delete
([
datastore
.
key
([
'Company'
,
123
]),
datastore
.
key
([
'Product'
,
'Computer'
])
],
(
err
,
apiResponse
)
=
>
{});
//-
// Returns a Promise if callback is omitted.
//-
datastore
.
delete
().
then
((
data
)
=
>
{
const
apiResponse
=
data
[
0
];
});
delete(keys, callback)
delete
(
keys
:
Entities
,
callback
:
DeleteCallback
)
:
void
;
Parameters
Name
Description
keys
Entities
callback
DeleteCallback
Returns
Type
Description
void
delete(keys, gaxOptions, callback)
delete
(
keys
:
Entities
,
gaxOptions
:
CallOptions
,
callback
:
DeleteCallback
)
:
void
;
Parameters
Name
Description
keys
Entities
gaxOptions
CallOptions
callback
DeleteCallback
Returns
Type
Description
void
get(keys, options)
get
(
keys
:
entity
.
Key
|
entity
.
Key
[],
options
?:
CreateReadStreamOptions
)
:
Promise<GetResponse>
;
Retrieve the entities identified with the specified key(s) in the current transaction. Get operations require a valid key to retrieve the key-identified entity from Datastore.
Parameters
Name
Description
keys
options
CreateReadStreamOptions
Optional configuration.
Returns
Type
Description
Promise
< GetResponse
>
//-
// Get a single entity.
//-
const
key
=
datastore
.
key
([
'Company'
,
123
]);
datastore
.
get
(
key
,
(
err
,
entity
)
=
>
{});
//-
// Or, if you're using a transaction object.
//-
const
transaction
=
datastore
.
transaction
();
transaction
.
run
((
err
)
=
>
{
if
(
err
)
{
// Error handling omitted.
}
transaction
.
get
(
key
,
(
err
,
entity
)
=
>
{
if
(
err
)
{
// Error handling omitted.
}
transaction
.
commit
((
err
)
=
>
{
if
(
!
err
)
{
// Transaction committed successfully.
}
});
});
});
//-
// Get multiple entities at once with a callback.
//-
const
keys
=
[
datastore
.
key
([
'Company'
,
123
]),
datastore
.
key
([
'Product'
,
'Computer'
])
];
datastore
.
get
(
keys
,
(
err
,
entities
)
=
>
{});
//-
// Below is how to update the value of an entity with the help of the
// `save` method.
//-
datastore
.
get
(
key
,
(
err
,
entity
)
=
>
{
if
(
err
)
{
// Error handling omitted.
}
entity
.
newValue
=
true
;
datastore
.
save
({
key
:
key
,
data
:
entity
},
(
err
)
=
>
{});
});
//-
// Returns a Promise if callback is omitted.
//-
datastore
.
get
(
keys
).
then
((
data
)
=
>
{
const
entities
=
data
[
0
];
});
get(keys, callback)
get
(
keys
:
entity
.
Key
|
entity
.
Key
[],
callback
:
GetCallback
)
:
void
;
Returns
Type
Description
void
get(keys, options, callback)
get
(
keys
:
entity
.
Key
|
entity
.
Key
[],
options
:
CreateReadStreamOptions
,
callback
:
GetCallback
)
:
void
;
Parameters
Name
Description
keys
entity.Key
| entity.Key
[]
options
CreateReadStreamOptions
callback
GetCallback
Returns
Type
Description
void
merge(entities)
merge
(
entities
:
Entities
)
:
Promise<CommitResponse>
;
Merge the specified object(s). If a key is incomplete, its associated object is inserted and the original Key object is updated to contain the generated ID. For example, if you provide an incomplete key (one without an ID), the request will create a new entity and have its ID automatically assigned. If you provide a complete key, the entity will be get the data from datastore and merge with the data specified. By default, all properties are indexed. To prevent a property from being included in *all* indexes, you must supply an excludeFromIndexes
array.
Maps to , forcing the method to be upsert
.
Parameter
Name
Description
entities
Entities
Datastore key object(s).
Returns
Type
Description
Promise
< CommitResponse
>
merge(entities, callback)
merge
(
entities
:
Entities
,
callback
:
SaveCallback
)
:
void
;
Parameters
Name
Description
entities
Entities
callback
SaveCallback
Returns
Type
Description
void
prepareGaxRequest_(config, callback)
prepareGaxRequest_
(
config
:
RequestConfig
,
callback
:
Function
)
:
void
;
Parameters
Name
Description
config
RequestConfig
callback
Function
Returns
Type
Description
void
request_(config, callback)
request_
(
config
:
RequestConfig
,
callback
:
RequestCallback
)
:
void
;
Make a request to the API endpoint. Properties to indicate a transactional or non-transactional operation are added automatically.
Parameters
Name
Description
config
RequestConfig
Configuration object.
callback
RequestCallback
The callback function.
Returns
Type
Description
void
requestStream_(config)
requestStream_
(
config
:
RequestConfig
)
:
AbortableDuplex
;
Make a request as a stream.
Parameter
Name
Description
config
RequestConfig
Configuration object.
Returns
Type
Description
AbortableDuplex
runAggregationQuery(query, options)
runAggregationQuery
(
query
:
AggregateQuery
,
options
?:
RunQueryOptions
)
:
Promise<RunQueryResponse>
;
Parameters
Name
Description
query
AggregateQuery
options
RunQueryOptions
Returns
Type
Description
Promise
< RunQueryResponse
>
runAggregationQuery(query, options, callback)
runAggregationQuery
(
query
:
AggregateQuery
,
options
:
RunQueryOptions
,
callback
:
RequestCallback
)
:
void
;
Parameters
Name
Description
query
AggregateQuery
options
RunQueryOptions
callback
RequestCallback
Returns
Type
Description
void
runAggregationQuery(query, callback)
runAggregationQuery
(
query
:
AggregateQuery
,
callback
:
RequestCallback
)
:
void
;
Parameters
Name
Description
query
AggregateQuery
callback
RequestCallback
Returns
Type
Description
void
runQuery(query, options)
runQuery
(
query
:
Query
,
options
?:
RunQueryOptions
)
:
Promise<RunQueryResponse>
;
Datastore allows you to query entities by kind, filter them by property filters, and sort them by a property name. Projection and pagination are also supported.
The query is run, and the results are returned as the second argument to your callback. A third argument may also exist, which is a query object that uses the end cursor from the previous query as the starting cursor for the next query. You can pass that object back to this method to see if more results exist.
Parameters
Name
Description
query
options
RunQueryOptions
Optional configuration.
Returns
Type
Description
Promise
< RunQueryResponse
>
//-
// Where you see `transaction`, assume this is the context that's relevant
to
// your use, whether that be a Datastore or a Transaction object.
//-
const
query
=
datastore
.
createQuery
(
'Lion'
);
datastore
.
runQuery
(
query
,
(
err
,
entities
,
info
)
=
>
{
// entities = An array of records.
// Access the Key object for an entity.
const
firstEntityKey
=
entities
[
0
][
datastore
.
KEY
];
});
//-
// Or, if you're using a transaction object.
//-
const
transaction
=
datastore
.
transaction
();
transaction
.
run
((
err
)
=
>
{
if
(
err
)
{
// Error handling omitted.
}
transaction
.
runQuery
(
query
,
(
err
,
entities
)
=
>
{
if
(
err
)
{
// Error handling omitted.
}
transaction
.
commit
((
err
)
=
>
{
if
(
!
err
)
{
// Transaction committed successfully.
}
});
});
});
//-
// A keys-only query returns just the keys of the result entities instead
of
// the entities themselves, at lower latency and cost.
//-
const
keysOnlyQuery
=
datastore
.
createQuery
(
'Lion'
).
select
(
'__key__'
);
datastore
.
runQuery
(
keysOnlyQuery
,
(
err
,
entities
)
=
>
{
const
keys
=
entities
.
map
((
entity
)
=
>
{
return
entity
[
datastore
.
KEY
];
});
});
//-
// Returns a Promise if callback is omitted.
//-
datastore
.
runQuery
(
query
).
then
((
data
)
=
>
{
const
entities
=
data
[
0
];
});
runQuery(query, options, callback)
runQuery
(
query
:
Query
,
options
:
RunQueryOptions
,
callback
:
RunQueryCallback
)
:
void
;
Returns
Type
Description
void
runQuery(query, callback)
runQuery
(
query
:
Query
,
callback
:
RunQueryCallback
)
:
void
;
Returns
Type
Description
void
runQueryStream(query, options)
runQueryStream
(
query
:
Query
,
options
?:
RunQueryStreamOptions
)
:
Transform
;
Get a list of entities as a readable object stream.
See for a list of all available options.
Parameters
Name
Description
query
options
RunQueryStreamOptions
Optional configuration.
Returns
Type
Description
Transform
datastore
.
runQueryStream
(
query
)
.
on
(
'error'
,
console
.
error
)
.
on
(
'data'
,
(
entity
)
=
>
{
// Access the Key object for this entity.
const
key
=
entity
[
datastore
.
KEY
];
})
.
on
(
'info'
,
(
info
)
=
>
{})
.
on
(
'end'
,
()
=
>
{
// All entities retrieved.
});
//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
datastore
.
runQueryStream
(
query
)
.
on
(
'data'
,
(
entity
)
=
>
{
this
.
end
();
});
