<commit_before>:spring-data-commons-ref: https://docs.spring.io/spring-data/data-commons/docs/current/reference/html

== Spring Data Cloud Datastore

http://projects.spring.io/spring-data/[Spring Data] is an abstraction for storing and retrieving POJOs in numerous storage technologies.
Spring Cloud GCP adds Spring Data support for http://cloud.google.com/datastore/[Google Cloud Datastore].

Maven coordinates for this module only, using https://github.com/spring-cloud/spring-cloud-gcp/blob/master/spring-cloud-gcp-dependencies/pom.xml[Spring Cloud GCP BOM]:

[source,xml]
----
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-gcp-data-datastore</artifactId>
</dependency>
----

Gradle coordinates:

[source]
----
dependencies {
    compile group: 'org.springframework.cloud', name: 'spring-cloud-gcp-data-datastore'
}
----

We provide a link:../spring-cloud-gcp-starters/spring-cloud-gcp-starter-data-datastore[Spring Boot Starter for Spring Data Datastore], with which you can use our recommended auto-configuration setup.
To use the starter, see the coordinates below.


Maven:

[source,xml]
----
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-data-datastore</artifactId>
</dependency>
----

Gradle:

[source,subs="normal"]
----
dependencies {
    compile group: 'org.springframework.cloud', name: 'spring-cloud-gcp-starter-data-datastore'
}
----

This setup takes care of bringing in the latest compatible version of Cloud Java Cloud Datastore libraries as well.

=== Configuration

To setup Spring Data Cloud Datastore, you have to configure the following:

* Setup the connection details to Google Cloud Datastore.

==== Cloud Datastore settings

You can the use link:../spring-cloud-gcp-starters/spring-cloud-gcp-starter-data-datastore[Spring Boot Starter for Spring Data Datastore] to autoconfigure Google Cloud Datastore in your Spring application.
It contains all the necessary setup that makes it easy to authenticate with your Google Cloud project.
The following configuration options are available:

|===
| Name | Description | Required | Default value
| `spring.cloud.gcp.datastore.enabled` | Enables the Cloud Datastore client | No | `true`
| `spring.cloud.gcp.datastore.project-id` | GCP project ID where the Google Cloud Datastore API
is hosted, if different from the one in the <<spring-cloud-gcp-core,Spring Cloud GCP Core Module>>
| No |
| `spring.cloud.gcp.datastore.credentials.location` | OAuth2 credentials for authenticating with the
Google Cloud Datastore API, if different from the ones in the
<<spring-cloud-gcp-core,Spring Cloud GCP Core Module>> | No |
| `spring.cloud.gcp.datastore.credentials.encoded-key` | Base64-encoded OAuth2 credentials for authenticating with the
Google Cloud Datastore API, if different from the ones in the
<<spring-cloud-gcp-core,Spring Cloud GCP Core Module>> | No |
| `spring.cloud.gcp.datastore.credentials.scopes` |
https://developers.google.com/identity/protocols/googlescopes[OAuth2 scope] for Spring Cloud GCP
Cloud Datastore credentials | No | https://www.googleapis.com/auth/datastore
| `spring.cloud.gcp.datastore.namespace` | The Cloud Datastore namespace to use | No | the Default namespace of Cloud Datastore in your GCP project
|===

==== Repository settings

Spring Data Repositories can be configured via the `@EnableDatastoreRepositories` annotation on your main `@Configuration` class.
With our Spring Boot Starter for Spring Data Cloud Datastore, `@EnableDatastoreRepositories` is automatically added.
It is not required to add it to any other class, unless there is a need to override finer grain configuration parameters provided by https://github.com/spring-cloud/spring-cloud-gcp/blob/master/spring-cloud-gcp-data-datastore/src/main/java/org/springframework/cloud/gcp/data/datastore/repository/config/EnableDatastoreRepositories.java[`@EnableDatastoreRepositories`].

==== Autoconfiguration

Our Spring Boot autoconfiguration creates the following beans available in the Spring application context:

- an instance of `DatastoreTemplate`
- an instance of all user defined repositories extending `CrudRepository`, `PagingAndSortingRepository`, and `DatastoreRepository` (an extension of `PagingAndSortingRepository` with additional Cloud Datastore features) when repositories are enabled
- an instance of `Datastore` from the Google Cloud Java Client for Datastore, for convenience and lower level API access


=== Object Mapping

Spring Data Cloud Datastore allows you to map domain POJOs to Cloud Datastore kinds and entities via annotations:

[source,java]
----
@Entity(name = "traders")
public class Trader {

	@Id
	@Field(name = "trader_id")
	String traderId;

	String firstName;

	String lastName;

	@Transient
	Double temporaryNumber;
}
----

Spring Data Cloud Datastore will ignore any property annotated with `@Transient`. These properties will not be written to or read from Cloud Datastore.

==== Constructors

Simple constructors are supported on POJOs.
The constructor arguments can be a subset of the persistent properties.
Every constructor argument needs to have the same name and type as a persistent property on the entity and the constructor should set the property from the given argument.
Arguments that are not directly set to properties are not supported.

[source,java]
----
@Entity(name = "traders")
public class Trader {

	@Id
	@Field(name = "trader_id")
	String traderId;

	String firstName;

	String lastName;

	@Transient
	Double temporaryNumber;

	public Trader(String traderId, String firstName) {
	    this.traderId = traderId;
	    this.firstName = firstName;
	}
}
----


==== Kind

The `@Entity` annotation can provide the name of the Cloud Datastore kind that stores instances of the annotated class, one per row.

==== Keys

`@Id` identifies the property corresponding to the ID value.

You must annotate one of your POJO's fields as the ID value, because every entity in Cloud Datastore requires a single ID value:

[source,java]
----
@Entity(name = "trades")
public class Trade {
	@Id
	@Field(name = "trade_id")
	String tradeId;

	@Field(name = "trader_id")
	String traderId;

	String action;

	Double price;

	Double shares;

	String symbol;
}
----


Datastore has automatic ID allocation. If a POJO instance is written to Cloud Datastore with `null` as the ID value, then Spring Data Cloud Datastore will obtain a newly allocated ID value from Cloud Datastore and set that in the POJO for saving.


==== Fields

All accessible properties on POJOs are automatically recognized as a Cloud Datastore field.
Field naming is generated by the `PropertyNameFieldNamingStrategy` by default defined on the `DatastoreMappingContext` bean.
The `@Field` annotation optionally provides a different field name than that of the property.


==== Supported Types

Spring Data Cloud Datastore supports the following types for regular fields and elements of collections:

[options="header"]
|===
| Type| Stored as
| `com.google.cloud.Timestamp`|com.google.cloud.datastore.TimestampValue
| `com.google.cloud.datastore.Blob`|com.google.cloud.datastore.BlobValue
| `com.google.cloud.datastore.LatLng`|com.google.cloud.datastore.LatLngValue
| `java.lang.Boolean`, `boolean`|com.google.cloud.datastore.BooleanValue
| `java.lang.Double`, `double`|com.google.cloud.datastore.DoubleValue
| `java.lang.Long`, `long`|com.google.cloud.datastore.LongValue
| `java.lang.Integer`, `int`|com.google.cloud.datastore.LongValue
| `java.lang.String`|com.google.cloud.datastore.StringValue
| `com.google.cloud.datastore.Entity`|com.google.cloud.datastore.EntityValue<commit_msg>Datastore ref doc alloc key clarification (#1298)<commit_after>:spring-data-commons-ref: https://docs.spring.io/spring-data/data-commons/docs/current/reference/html

== Spring Data Cloud Datastore

http://projects.spring.io/spring-data/[Spring Data] is an abstraction for storing and retrieving POJOs in numerous storage technologies.
Spring Cloud GCP adds Spring Data support for http://cloud.google.com/datastore/[Google Cloud Datastore].

Maven coordinates for this module only, using https://github.com/spring-cloud/spring-cloud-gcp/blob/master/spring-cloud-gcp-dependencies/pom.xml[Spring Cloud GCP BOM]:

[source,xml]
----
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-gcp-data-datastore</artifactId>
</dependency>
----

Gradle coordinates:

[source]
----
dependencies {
    compile group: 'org.springframework.cloud', name: 'spring-cloud-gcp-data-datastore'
}
----

We provide a link:../spring-cloud-gcp-starters/spring-cloud-gcp-starter-data-datastore[Spring Boot Starter for Spring Data Datastore], with which you can use our recommended auto-configuration setup.
To use the starter, see the coordinates below.


Maven:

[source,xml]
----
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-data-datastore</artifactId>
</dependency>
----

Gradle:

[source,subs="normal"]
----
dependencies {
    compile group: 'org.springframework.cloud', name: 'spring-cloud-gcp-starter-data-datastore'
}
----

This setup takes care of bringing in the latest compatible version of Cloud Java Cloud Datastore libraries as well.

=== Configuration

To setup Spring Data Cloud Datastore, you have to configure the following:

* Setup the connection details to Google Cloud Datastore.

==== Cloud Datastore settings

You can the use link:../spring-cloud-gcp-starters/spring-cloud-gcp-starter-data-datastore[Spring Boot Starter for Spring Data Datastore] to autoconfigure Google Cloud Datastore in your Spring application.
It contains all the necessary setup that makes it easy to authenticate with your Google Cloud project.
The following configuration options are available:

|===
| Name | Description | Required | Default value
| `spring.cloud.gcp.datastore.enabled` | Enables the Cloud Datastore client | No | `true`
| `spring.cloud.gcp.datastore.project-id` | GCP project ID where the Google Cloud Datastore API
is hosted, if different from the one in the <<spring-cloud-gcp-core,Spring Cloud GCP Core Module>>
| No |
| `spring.cloud.gcp.datastore.credentials.location` | OAuth2 credentials for authenticating with the
Google Cloud Datastore API, if different from the ones in the
<<spring-cloud-gcp-core,Spring Cloud GCP Core Module>> | No |
| `spring.cloud.gcp.datastore.credentials.encoded-key` | Base64-encoded OAuth2 credentials for authenticating with the
Google Cloud Datastore API, if different from the ones in the
<<spring-cloud-gcp-core,Spring Cloud GCP Core Module>> | No |
| `spring.cloud.gcp.datastore.credentials.scopes` |
https://developers.google.com/identity/protocols/googlescopes[OAuth2 scope] for Spring Cloud GCP
Cloud Datastore credentials | No | https://www.googleapis.com/auth/datastore
| `spring.cloud.gcp.datastore.namespace` | The Cloud Datastore namespace to use | No | the Default namespace of Cloud Datastore in your GCP project
|===

==== Repository settings

Spring Data Repositories can be configured via the `@EnableDatastoreRepositories` annotation on your main `@Configuration` class.
With our Spring Boot Starter for Spring Data Cloud Datastore, `@EnableDatastoreRepositories` is automatically added.
It is not required to add it to any other class, unless there is a need to override finer grain configuration parameters provided by https://github.com/spring-cloud/spring-cloud-gcp/blob/master/spring-cloud-gcp-data-datastore/src/main/java/org/springframework/cloud/gcp/data/datastore/repository/config/EnableDatastoreRepositories.java[`@EnableDatastoreRepositories`].

==== Autoconfiguration

Our Spring Boot autoconfiguration creates the following beans available in the Spring application context:

- an instance of `DatastoreTemplate`
- an instance of all user defined repositories extending `CrudRepository`, `PagingAndSortingRepository`, and `DatastoreRepository` (an extension of `PagingAndSortingRepository` with additional Cloud Datastore features) when repositories are enabled
- an instance of `Datastore` from the Google Cloud Java Client for Datastore, for convenience and lower level API access


=== Object Mapping

Spring Data Cloud Datastore allows you to map domain POJOs to Cloud Datastore kinds and entities via annotations:

[source,java]
----
@Entity(name = "traders")
public class Trader {

	@Id
	@Field(name = "trader_id")
	String traderId;

	String firstName;

	String lastName;

	@Transient
	Double temporaryNumber;
}
----

Spring Data Cloud Datastore will ignore any property annotated with `@Transient`. These properties will not be written to or read from Cloud Datastore.

==== Constructors

Simple constructors are supported on POJOs.
The constructor arguments can be a subset of the persistent properties.
Every constructor argument needs to have the same name and type as a persistent property on the entity and the constructor should set the property from the given argument.
Arguments that are not directly set to properties are not supported.

[source,java]
----
@Entity(name = "traders")
public class Trader {

	@Id
	@Field(name = "trader_id")
	String traderId;

	String firstName;

	String lastName;

	@Transient
	Double temporaryNumber;

	public Trader(String traderId, String firstName) {
	    this.traderId = traderId;
	    this.firstName = firstName;
	}
}
----


==== Kind

The `@Entity` annotation can provide the name of the Cloud Datastore kind that stores instances of the annotated class, one per row.

==== Keys

`@Id` identifies the property corresponding to the ID value.

You must annotate one of your POJO's fields as the ID value, because every entity in Cloud Datastore requires a single ID value:

[source,java]
----
@Entity(name = "trades")
public class Trade {
	@Id
	@Field(name = "trade_id")
	String tradeId;

	@Field(name = "trader_id")
	String traderId;

	String action;

	Double price;

	Double shares;

	String symbol;
}
----


Datastore has automatic ID allocation.
If a POJO instance is written to Cloud Datastore with `null` as the ID value, then Spring Data Cloud Datastore will obtain a newly allocated ID value from Cloud Datastore and set that in the POJO for saving.
Because primitive `long` ID properties cannot be `null` and default to `0`, keys will not be allocated.

==== Fields

All accessible properties on POJOs are automatically recognized as a Cloud Datastore field.
Field naming is generated by the `PropertyNameFieldNamingStrategy` by default defined on the `DatastoreMappingContext` bean.
The `@Field` annotation optionally provides a different field name than that of the property.


==== Supported Types

Spring Data Cloud Datastore supports the following types for regular fields and elements of collections:

[options="header"]
|===
| Type| Stored as
| `com.google.cloud.Timestamp`|com.google.cloud.datastore.TimestampValue
| `com.google.cloud.datastore.Blob`|com.google.cloud.datastore.BlobValue
| `com.google.cloud.datastore.LatLng`|com.google.cloud.datastore.LatLngValue
| `java.lang.Boolean`, `boolean`|com.google.cloud.datastore.BooleanValue
| `java.lang.Double`, `double`|com.google.cloud.datastore.DoubleValue
| `java.lang.Long`, `long`|com.google.cloud.datastore.LongValue
| `java.lang.Integer`, `int`|com.google.cloud.datastore.LongValue
| `java.lang.String`|com.google.cloud.datastore.StringValue
| `com.google.cloud.datastore.Entity`|com.google.cloud.datastore.EntityValue
{'fraction_non_alphanumeric': 0.09529662935886653, 'fraction_numerical': 0.0009704341075240992, 'mean_word_length': 4.886519421172887, 'pattern_counts': {'":': 0, '<': 39, '<?xml version=': 0, '>': 39, 'https://': 10, 'lorem ipsum': 0, 'www.': 2, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4609963', 'n_tokens_mistral': 4535, 'n_tokens_neox': 4366, 'n_words': 1549}