ANSI Joins

本章介绍了如何在实体之间使用 ANSI 关联。从 5.5 版本开始，Couchbase 服务器支持使用字段关联文档的 ANSI 关联。以前版本允许索引和查找关联，SDC 仅通过 SDK 直接查询支持这些关联。

This chapter describes hows ANSI joins can be used across entities. Since 5.5 version, Couchbase server provides support for ANSI joins for joining documents using fields. Previous versions allowed index & lookup joins, which were supported in SDC only by querying directly through the SDK.

存储库之间的实体关系可以是一对一或一对多。通过定义此类关系，可以获取关联实体的同步视图。

Relationships between entities across repositories can be one to one or one to many. By defining such relationships, a synchronized view of associated entities can be fetched.

Configuration

可以通过使用 @N1qlJoin 为实体的属性引用添加注解来获取关联实体。前缀 lks 指的是左键空间（当前实体），而 rks 指的是右键空间（关联实体）。@N1qlJoin 注解的必需元素是 on 子句，该子句是布尔表达式，表示左键空间 (lks) 和右键空间 (rks) 之间的关联条件，可以是字段、常量表达式或任何复杂的 N1QL 表达式。该注解上还可以存在可选的 where 子句，它同样使用 lks 指当前实体，使用 rks 指关联实体。

Associated entities can be fetched by annotating the entity’s property reference with @N1qlJoin. The prefix lks refers to left-hand side key space (current entity) and rks refers to the right-hand side key space (associated entity). The required element for @N1qlJoin annotation is the on clause, a boolean expression representing the join condition between the left-hand side (lks) and the right-hand side (rks), which can be fields, constant expressions or any complex N1QL expression. There could also be an optional where clause specified on the annotation for the join, similarly using lks to refer the current entity and rks to refer the associated entity.

Example 1. Annotation for ANSI Join

@Document
public class Author {
      @Id
      String id;

      String name;

      @N1qlJoin(on = "lks.name=rks.authorName")
      List<Book> books;

      @N1qlJoin(on = "lks.name=rks.name")
      Address address;
     ...
}

Lazy fetching

可以在首次访问属性时延迟获取关联实体，这样可以节省在加载实体时获取比所需更多的额外数据。要延迟加载关联实体，@N1qlJoin 注解的元素 fetchType 必须设置为 FetchType.LAZY。默认值为 FetchType.IMMEDIATE。

Associated entities can be lazily fetched upon the first access of the property, this could save on fetching more data than required when loading the entity. To load the associated entities lazily, @N1qlJoin annotation’s element fetchType has to be set to FetchType.LAZY. The default is FetchType.IMMEDIATE.

Example 2. Configuration for lazy fetch

@N1qlJoin(on = "lks.name=rks.authorName", fetchType = FetchType.LAZY)
List<Book> books;

ANSI Join Hints

Use Index Hint

@N1qlJoin 上的 index 元素可用于为 lks（当前实体）索引提供提示，而 rightIndex 元素可用于为 rks（关联实体）索引提供提示。

index element on the @N1qlJoin can be used to provided the hint for the lks (current entity) index and rightIndex element can be used to provided the rks (associated entity) index.

Hash Join Hint

如果关联类型为哈希关联，则可以为 rks（关联实体）指定哈希侧。如果关联实体在构建侧，则可以将其指定为 HashSide.BUILD，否则为 HashSide.PROBE。

If the join type is going to be hash join, the hash side can be specified for the rks (associated entity). If the associated entity is on the build side, it can be specified as HashSide.BUILD else HashSide.PROBE.

Use Keys Hint

@N1qlJoin 注解上的 keys 元素可用于指定唯一的文档键以限制关联键空间。

keys element on the @N1qlJoin annotation can be used to specify unique document keys to restrict the join key space.