Merge pull request #2 from Microsoft/readme

update readme
This commit is contained in:
yungez 2017-09-19 11:38:35 +08:00 коммит произвёл GitHub
Родитель 3de8cea808 e9dbffd3b3
Коммит 8c71fb30ec
1 изменённых файлов: 23 добавлений и 11 удалений

Просмотреть файл

@ -1,5 +1,5 @@
## Spring Data for Azure Cosmos DB DocumentDB API
[Azure Cosmos DB](https://docs.microsoft.com/en-us/azure/cosmos-db/introduction) is a globally-distributed database service that allows developers to work with data using a variety of standard APIs, such as DocumentDB, MongoDB, Graph, and Table APIs. Azure DocumentDB Spring Data provides initial Spring Data support for [Azure Cosmos DB Document API](https://docs.microsoft.com/en-us/azure/cosmos-db/documentdb-introduction) based on Spring Data framework, the other 3 APIs are not supported in this package. Key functionalities supported so far include save, delete and find. More features will coming soon.
[Azure Cosmos DB](https://docs.microsoft.com/en-us/azure/cosmos-db/introduction) is a globally-distributed database service that allows developers to work with data using a variety of standard APIs, such as DocumentDB, MongoDB, Graph, and Table APIs. Azure Cosmos DB DocumentDB Spring Data provides initial Spring Data support for [Azure Cosmos DB Document API](https://docs.microsoft.com/en-us/azure/cosmos-db/documentdb-introduction) based on Spring Data framework, the other 3 APIs are not supported in this package. Key functionalities supported are listed at below. More features will coming soon.
## Sample Code
Please refer to [sample project here](./samplecode).
@ -13,12 +13,12 @@ Please refer to [sample project here](./samplecode).
- delete by Id
- delete entity
- Spring Data [@Id](https://github.com/spring-projects/spring-data-commons/blob/db62390de90c93a78743c97cc2cc9ccd964994a5/src/main/java/org/springframework/data/annotation/Id.java) annotation.
There're 2 ways to map a field in domain class to `id` of Azure Cosmos DB document.
There're 2 ways to map a field in domain class to `id` field of Azure Cosmos DB document.
- annotate a field in domain class with `@Id`, this field will be mapped to document `id` in Cosmos DB.
- set name of this field to `id`, this field will be mapped to document `id` in Cosmos DB.
- Custom collection Name.
By default, collection name will be class name of user domain class. To customize it, add annoataion `@Document(collection="myCustomCollectionName")` to your domain class, that's all.
- Supports [Azure Cosmos DB partition](https://docs.microsoft.com/en-us/azure/cosmos-db/partition-data). To specify a field of your domain class to be partition key field, just annotate it with `@PartitionKey`. When you do CRUD operation, pls specify your partition value. For more sample on partition CRUD, pls refer to [test here](./test/java/com/microsoft/azure/spring/data/documentdb/repository/AddressRepositoryIT.java)
By default, collection name will be class name of user domain class. To customize it, add annoataion `@Document(collection="myCustomCollectionName")` to domain class, that's all.
- Supports [Azure Cosmos DB partition](https://docs.microsoft.com/en-us/azure/cosmos-db/partition-data). To specify a field of domain class to be partition key field, just annotate it with `@PartitionKey`. When you do CRUD operation, pls specify your partition value. For more sample on partition CRUD, pls refer to [test here](./src/test/java/com/microsoft/azure/spring/data/cosmosdb/documentdb/repository/AddressRepositoryIT.java)
## Quick Start
@ -35,10 +35,11 @@ If you are using Maven, add the following dependency.
```
### Setup Configuration
Setup Azure Cosmos DB DocumentDB configuration class. Enabling Spring Data Azure DocumentDB repository support is auto-configured.
Setup Azure Cosmos DB DocumentDB configuration class.
```
@Configuration
@EnableDocumentDbRepositories
public class AppConfiguration extends AbstractDocumentDbConfiguration {
@Value("${azure.documentdb.uri}")
@ -94,10 +95,10 @@ public class User {
}
}
```
`id` field will be used as document id in Azure DocumentDB. If you want use another field like `emailAddress` as document `id`, just annotate that field with `@Id` annotation.
`id` field will be used as document id in Azure Cosmos DB. If you want use another field like `emailAddress` as document `id`, just annotate that field with `@Id` annotation.
Annotation `@Document(collection="mycollection")` is used to specify collection name of your document in Azure Cosmos DB.
Annotation `@PartitionKey` on lastName field is used to specify this field be partition key in Azure Cosmos DB.
Annotation `@Document(collection="mycollection")` is used to specify collection name in Azure Cosmos DB.
Annotation `@PartitionKey` on `lastName` field is used to specify this field be partition key in Azure Cosmos DB.
```
@Document(collection = "mycollection")
@ -121,7 +122,7 @@ public interface UserRepository extends DocumentDbRepository<User, String> {
}
```
So far DocumentDbRepository provides basic save, delete and find operations. More operations will be supported later.
So far DocumentDbRepository provides basic save, delete, update and find operations. More operations will be supported later.
### Create an Application class
Here create an application class with all the components
@ -153,5 +154,16 @@ public class SampleApplication implements CommandLineRunner {
```
Autowired UserRepository interface, then can do save, delete and find operations. Azure Cosmos DB DocumentDB Spring Data uses the DocumentTemplate to execute the queries behind *find*, *save* methods. You can use the template yourself for more complex queries.
## Further info
If you'd like to save effort of configuration, you could directly use Azure Cosmos DB DocumentDB API Spring boot starter at [here](../azure-documentdb-spring-boot-starter).
## Filing Issues
If you encounter any bug, please file an issue [here](https://github.com/Microsoft/spring-data-azure-cosmosdb-documentdb/issues/new).
To suggest a new feature or changes that could be made, file an issue the same way you would for a bug.
## Pull Requests
Pull requests are welcome. To open your own pull request, click [here](https://github.com/Microsoft/spring-data-azure-cosmosdb-documentdb/compare). When creating a pull request, make sure you are pointing to the fork and branch that your changes were made in.
## Code of Conduct
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.