apache-ignite
128 строк · 4.6 Кб
1// Licensed to the Apache Software Foundation (ASF) under one or more
2// contributor license agreements. See the NOTICE file distributed with
3// this work for additional information regarding copyright ownership.
4// The ASF licenses this file to You under the Apache License, Version 2.0
5// (the "License"); you may not use this file except in compliance with
6// the License. You may obtain a copy of the License at
7//
8// http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15= Affinity Colocation
16
17In many cases it is beneficial to colocate different entries if they are often accessed together.
18In this way, multi-entry queries are executed on one node (where the objects are stored).
19This concept is known as _affinity colocation_.
20
21Entries are assigned to partitions by the affinity function.
22The objects that have the same affinity keys go to the same partitions.
23This allows you to design your data model in such a way that related entries are stored together.
24"Related" here refers to the objects that are in a parent-child relationship or objects that are often queried together.
25
26For example, let's say you have `Person` and `Company` objects, and each person has the `companyId` field that indicates the company the person works for.
27By specifying the `Person.companyId` and `Company.ID` as affinity keys, you ensure that all the persons working for the same company are stored on the same node, where the company object is stored as well.
28Queries that request persons working for a specific company are processed on a single node.
29
30////
31The following image shows how data is distributed with the default affinity configuration:
32
33*TODO*
34
35And here is how data is distributed when you colocate persons with the companies:
36
37*TODO image*
38////
39
40You can also colocate a computation task with the data. See link:distributed-computing/collocated-computations[Colocating Computations With Data].
41////
42*TODO: add examples and use cases*
43////
44== Configuring Affinity Key
45
46If you do not specify the affinity key explicitly, the cache key is used as the default affinity key.
47If you create your caches as SQL tables using SQL statements, the PRIMARY KEY is the default affinity key.
48
49If you want to colocate data from two caches by a different field, you have to use a complex object as the key. That object usually contains a field that uniquely identifies the object in that cache and a field that you want to use for colocation.
50
51There are several ways to configure a custom affinity field within the custom key, which are described below.
52
53The following example illustrates how you can colocate the person objects with the company objects using a custom key class and the `@AffinityKeyMapped` annotation.
54
55:javaSourceFile: {javaCodeDir}/AffinityCollocationExample.java
56:dotnetSourceFile: code-snippets/dotnet/AffinityCollocation.cs
57:cppSourceFile: code-snippets/cpp/src/affinity_collocation.cpp
58
59[tabs]
60--
61tab:Java[]
62[source,java]
63----
64include::{javaSourceFile}[tags=collocation;!config-with-key-configuration;!affinity-key-class,indent=0]
65----
66tab:C#/.NET[]
67[source,csharp]
68----
69include::{dotnetSourceFile}[tag=affinityCollocation,indent=0]
70----
71tab:C++[]
72[source,cpp]
73----
74include::{cppSourceFile}[tag=affinity-collocation,indent=0]
75----
76
77tab:SQL[]
78[source,sql]
79----
80CREATE TABLE IF NOT EXISTS Person (
81id int,
82city_id int,
83name varchar,
84company_id varchar,
85PRIMARY KEY (id, city_id)
86) WITH "template=partitioned,backups=1,affinity_key=company_id";
87
88CREATE TABLE IF NOT EXISTS Company (
89id int,
90name varchar,
91PRIMARY KEY (id)
92) WITH "template=partitioned,backups=1";
93----
94--
95
96You can also configure the affinity key field in the cache configuration by using the `CacheKeyConfiguration` class.
97
98[tabs]
99--
100tab:Java[]
101[source,java]
102----
103include::{javaSourceFile}[tag=config-with-key-configuration,indent=0]
104----
105tab:C#/.NET[]
106[source,csharp]
107----
108include::{dotnetSourceFile}[tag=config-with-key-configuration,indent=0]
109----
110tab:C++[unsupported]
111--
112
113Instead of defining a custom key class, you can use the `AffinityKey` class, which is designed specifically for the purpose of using custom affinity mapping.
114
115[tabs]
116--
117tab:Java[]
118[source,java]
119----
120include::{javaSourceFile}[tag=affinity-key-class,indent=0]
121----
122tab:C#/.NET[]
123[source,csharp]
124----
125include::{dotnetSourceFile}[tag=affinity-key-class,indent=0]
126----
127tab:C++[unsupported]
128--
129