Multiple Buckets and Spatial View Queries in Spring Data Couchbase – Spring Data Couchbase中的多桶和空间视图查询

最后修改: 2016年 6月 4日


1. Introduction


In this third tutorial on Spring Data Couchbase, we demonstrate the configuration required to support a Couchbase data model that spans multiple buckets, and we introduce the use of Spatial views for querying multi-dimensional data.

在这篇关于Spring Data Couchbase的第三篇教程中,我们演示了支持跨越多个桶的Couchbase数据模型所需的配置,并介绍了使用空间视图来查询多维数据。

2. Data Model


In addition to the Person entity from our first tutorial and the Student entity from our second tutorial, we define a Campus entity for this tutorial:


public class Campus {
    private String id;

    private String name;

    private Point location;

    // standard getters and setters

3. Java Configuration for Multiple Couchbase Buckets


In order to use multiple buckets in your project, you will need to use version 2.0.0 or later of the Spring Data Couchbase module, and you will need to use a Java-based configuration, because the XML-based configuration supports only single-bucket scenarios.

为了在你的项目中使用多个桶,你需要使用2.0.0或更高版本的Spring Data Couchbase模块,而且你需要使用基于Java的配置,因为基于XML的配置只支持单桶的情况。

Here is the dependency that we include in our Maven pom.xml file:

以下是我们在Maven pom.xml文件中包含的依赖性。


3.1. Defining the Bucket Bean

3.1.定义Bucket Bean

In our Introduction to Spring Data Couchbase tutorial, we designated “baeldung” as the name of our default Couchbase bucket for use with Spring Data.

在我们的Spring Data Couchbase入门教程中,我们指定“baeldung”作为默认的Couchbase桶的名称,用于Spring Data。

We will store Campus entities in the “baeldung2” bucket.


To make use of a second bucket, we first must define a @Bean for the Bucket itself in our Couchbase configuration class:


public Bucket campusBucket() throws Exception {
    return couchbaseCluster().openBucket("baeldung2", "");

3.2. Configuring the Template Bean


Next, we define a @Bean for the CouchbaseTemplate to be used with this bucket:


public CouchbaseTemplate campusTemplate() throws Exception {
    CouchbaseTemplate template = new CouchbaseTemplate(
      couchbaseClusterInfo(), campusBucket(),
      mappingCouchbaseConverter(), translationService());
    return template;

3.3. Mapping the Repositories


Finally, we define a custom mapping of Couchbase repository operations so that the Campus entity class will use the new template and bucket, while other entity classes will continue to use the default template and bucket:


public void configureRepositoryOperationsMapping(
  RepositoryOperationsMapping baseMapping) {
    try {
        baseMapping.mapEntity(Campus.class, campusTemplate());
    } catch (Exception e) {
        //custom Exception handling

4. Querying Spatial or Multi-Dimensional Data


Couchbase provides native support for running bounding box queries against two-dimensional data, such as geographical data, using a special type of view known as a Spatial view.

Couchbase提供了对二维数据(如地理数据)运行边界框查询的本地支持,使用一种被称为Spatial view的特殊类型的视图。

A bounding box query is a range query that uses the southwestern-most [x,y] point of the box as its startRange parameter and the northwestern-most [x,y] point as its endRange parameter.


Spring Data extends Couchbase’s native bounding box query feature to queries involving circles and polygons using an algorithm that seeks to eliminate false positive matches, and it also provides support for queries involving more than two dimensions.

Spring Data将Couchbase的原生边界框查询功能扩展到了涉及圆形和多边形的查询,使用的算法旨在消除错误的正面匹配,它还为涉及两个以上维度的查询提供了支持。

Spring Data simplifies the creation of multi-dimensional queries through a set of keywords that can be used to define derived queries in Couchbase repositories.

Spring Data通过一组关键字简化了多维查询的创建,这些关键字可以用来定义Couchbase资源库中的衍生查询。

4.1. Supported Data Types


Spring Data Couchbase repository queries support data types from the package, including Point, Box, Circle, Polygon, and Distance.

Spring Data Couchbase资源库的查询支持来自包的数据类型,包括Point, Box, Circle, Polygon, Distance

4.2. Derived Query Keywords


In addition to the standard Spring Data repository keywords, Couchbase repositories support the following keywords in derived queries involving two dimensions:

除了标准的Spring Data存储库关键字外,Couchbase存储库在涉及两个维度的衍生查询中支持以下关键字。

  • Within, InWithin (takes two Point parameters defining a bounding box)
  • Near, IsNear (takes a Point and Distance as parameters)

And the following keywords may be used for queries involving more than two dimensions:


  • Between (for adding a single numerical value to both the startRange and endRange)
  • GreaterThan, GreaterThanEqual, After (for adding a single numerical value to the startRange)
  • LessThan, LessThanEqual, Before (for adding a single numerical value to the endRange)

Here are some examples of derived query methods using these keywords:


  • findByLocationNear
  • findByLocationWithin
  • findByLocationNearAndPopulationGreaterThan
  • findByLocationWithinAndAreaLessThan
  • findByLocationNearAndTuitionBetween

5. Defining the Repository


Repository methods backed by Spatial views must be decorated with the @Dimensional annotation, which specifies the design document name, view name, and number of dimensions used to define the view’s key (default 2 if not otherwise specified).


5.1. The CampusRespository Interface


Here in our CampusRepository interface, we declare two methods — one that uses traditional Spring Data keywords, backed by a MapReduce view, and one that uses dimensional Spring Data keywords, backed by a Spatial view:

在我们的CampusRepository接口中,我们声明了两个方法–一个使用传统的Spring Data关键字,由MapReduce视图支持,另一个使用Spring Data关键字,由空间视图支持。

public interface CampusRepository extends CrudRepository<Campus, String> {

    @View(designDocument="campus", viewName="byName")
    Set<Campus> findByName(String name);

    @Dimensional(dimensions=2, designDocument="campus_spatial",
    Set<Campus> findByLocationNear(Point point, Distance distance);

5.2. Spatial Views


Spatial views are written as JavaScript functions, much like MapReduce views. Unlike MapReduce views, which consist of both a map function and a reduce function, Spatial views consist of only a spatial function and may not coexist in the same Couchbase design document as MapReduce views.


For our Campus entities, we will create a design document named “campus_spatial” containing a Spatial view named “byLocation” with the following function:


function (doc) {
  if (doc.location &&
      doc._class == "") {
    emit([doc.location.x, doc.location.y], null);

As this example demonstrates, when you write a Spatial view function, the key used in the emit function call must be an array of two or more values.


5.3. MapReduce Views


To provide full support for our repository, we must create a design document named “campus” containing two MapReduce views: “all” and “byName”.


Here is the map function for the “all” view:


function (doc, meta) {
  if(doc._class == "") {    
    emit(, null);

And here is the map function for the “byName” view:


function (doc, meta) {
  if(doc._class == "" && {    
    emit(, null);

6. Conclusion


We showed how to configure your Spring Data Couchbase project to support the use of multiple buckets, and we demonstrated how to use the repository abstraction to write spatial view queries against multi-dimensional data.

我们展示了如何配置你的Spring Data Couchbase项目以支持多桶的使用,我们还演示了如何使用存储库的抽象来编写针对多维数据的空间视图查询。

You can view the complete source code for this tutorial in the github project.


To learn more about Spring Data Couchbase, visit the official Spring Data Couchbase project site.

要了解有关Spring Data Couchbase的更多信息,请访问官方的Spring Data Couchbase>项目网站。