This is an automated email from the ASF dual-hosted git repository.
sk0x50 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ignite-3.git
The following commit(s) were added to refs/heads/main by this push:
new f91a642951 IGNITE-19184 Added javadocs and md file to describe node
attributes and distribution zone filters (#2188)
f91a642951 is described below
commit f91a6429513629d2906e88a14b9bb35e2dc64172
Author: Mirza Aliev <[email protected]>
AuthorDate: Thu Jun 15 12:30:13 2023 +0400
IGNITE-19184 Added javadocs and md file to describe node attributes and
distribution zone filters (#2188)
---
.../NodeAttributeConfigurationSchema.java | 7 ++-
.../management/topology/api/LogicalNode.java | 7 ++-
.../distributionzones/DistributionZoneManager.java | 2 +
.../DistributionZoneConfigurationSchema.java | 2 +
modules/distribution-zones/tech-notes/filters.md | 70 ++++++++++++++++++++++
5 files changed, 85 insertions(+), 3 deletions(-)
diff --git
a/modules/cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/configuration/NodeAttributeConfigurationSchema.java
b/modules/cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/configuration/NodeAttributeConfigurationSchema.java
index 55b4479550..cb52ebf3a2 100644
---
a/modules/cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/configuration/NodeAttributeConfigurationSchema.java
+++
b/modules/cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/configuration/NodeAttributeConfigurationSchema.java
@@ -22,8 +22,11 @@ import
org.apache.ignite.configuration.annotation.InjectedName;
import org.apache.ignite.configuration.annotation.Value;
/**
- * Node's attribute configuration schema.
- * TODO: add proper javadocs when filtering feature will be closer to the end
https://issues.apache.org/jira/browse/IGNITE-19184
+ * Node's attribute configuration schema. User can specify any number of pairs
(key, attribute) for a node through the local configuration
+ * of a node, and also can specify a filter through the SQL syntax of
distribution zones. Any time data nodes will be recalculated,
+ * corresponding filter will be applied to set of nodes with pre-defined
attributes.
+ *
+ * @see <a
href="https://github.com/apache/ignite-3/blob/main/modules/distribution-zones/tech-notes/filters.md";>Filter
documentation</a>
*/
@Config
public class NodeAttributeConfigurationSchema {
diff --git
a/modules/cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/topology/api/LogicalNode.java
b/modules/cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/topology/api/LogicalNode.java
index ce808d4a50..9ff7789dcd 100644
---
a/modules/cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/topology/api/LogicalNode.java
+++
b/modules/cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/topology/api/LogicalNode.java
@@ -28,7 +28,12 @@ import org.apache.ignite.network.NetworkAddress;
* Representation of a logical node in a cluster.
*/
public class LogicalNode extends ClusterNode {
- /** Node's attributes. */
+ /**
+ * Node's attributes.
+ *
+ * @see <a
href="https://github.com/apache/ignite-3/blob/main/modules/distribution-zones/tech-notes/filters.md";>Filter
+ * documentation</a>
+ */
@IgniteToStringInclude
private final Map<String, String> nodeAttributes;
diff --git
a/modules/distribution-zones/src/main/java/org/apache/ignite/internal/distributionzones/DistributionZoneManager.java
b/modules/distribution-zones/src/main/java/org/apache/ignite/internal/distributionzones/DistributionZoneManager.java
index 92a98f7ead..9666848b01 100644
---
a/modules/distribution-zones/src/main/java/org/apache/ignite/internal/distributionzones/DistributionZoneManager.java
+++
b/modules/distribution-zones/src/main/java/org/apache/ignite/internal/distributionzones/DistributionZoneManager.java
@@ -230,6 +230,8 @@ public class DistributionZoneManager implements
IgniteComponent {
* Local mapping of {@code nodeId} -> node's attributes, where {@code
nodeId} is a node id, that changes between restarts.
* This map is updated every time we receive a topology event in a {@code
topologyWatchListener}.
* TODO: https://issues.apache.org/jira/browse/IGNITE-19491 properly clean
up this map
+ *
+ * @see <a
href="https://github.com/apache/ignite-3/blob/main/modules/distribution-zones/tech-notes/filters.md";>Filter
documentation</a>
*/
private final Map<String, Map<String, String>> nodesAttributes;
diff --git
a/modules/distribution-zones/src/main/java/org/apache/ignite/internal/distributionzones/configuration/DistributionZoneConfigurationSchema.java
b/modules/distribution-zones/src/main/java/org/apache/ignite/internal/distributionzones/configuration/DistributionZoneConfigurationSchema.java
index 4db3f9ea82..e1dd497b8e 100644
---
a/modules/distribution-zones/src/main/java/org/apache/ignite/internal/distributionzones/configuration/DistributionZoneConfigurationSchema.java
+++
b/modules/distribution-zones/src/main/java/org/apache/ignite/internal/distributionzones/configuration/DistributionZoneConfigurationSchema.java
@@ -80,6 +80,8 @@ public class DistributionZoneConfigurationSchema {
/**
* Filter to form nodes which must be included to data nodes of this zone.
* Default value is {@code $..*}, which is a {@link
com.jayway.jsonpath.JsonPath} expression for including all attributes of nodes.
+ *
+ * @see <a
href="https://github.com/apache/ignite-3/blob/main/modules/distribution-zones/tech-notes/filters.md";>Filter
documentation</a>
*/
@ValidFilter
@Value(hasDefault = true)
diff --git a/modules/distribution-zones/tech-notes/filters.md
b/modules/distribution-zones/tech-notes/filters.md
new file mode 100644
index 0000000000..0cad552679
--- /dev/null
+++ b/modules/distribution-zones/tech-notes/filters.md
@@ -0,0 +1,70 @@
+## Introduction
+
+[IEP about Distribution
Zones](https://cwiki.apache.org/confluence/display/IGNITE/IEP-101%3A+Distribution+Zones)
includes the feature for
+filtering data nodes. It allows users to specify which nodes should be
included to data nodes of a specified zone.
+It is implemented in the way that user can specify any number of pairs (key,
attribute) for a node through the local configuration
+of a node, and also can specify a filter through the SQL syntax of
distribution zones. Any time data nodes will be recalculated,
+corresponding filter will be applied to set of nodes with pre-defined
attributes, so resulting data nodes will be filtered according to
+user's filter.
+
+## Node's attributes
+Using mechanism of specifying a local configuration of a node, it is possible
to add attributes to a node, so they could be
+used in a data nodes calculation and could be filtered taking into account
this attributes. From the technical point of view,
+node's attributes are represented through the JSON mechanism, so all
corresponding rules for JSON data are applied to node's attributes.
+
+In the `ignite-config.conf` it looks like this:
+
+```
+nodeAttributes.nodeAttributes {
+ region.attribute = "US"
+ storage.attribute = "SSD"
+}
+```
+
+or like this in a `ignite-config.json`:
+
+```
+{
+ "nodeAttributes":{
+ "nodeAttributes":{
+ "region":{
+ "attribute":"US"
+ },
+ "storage":{
+ "attribute":"SSD"
+ }
+ }
+ }
+}
+```
+
+Note that node's attributes could be changed only after node's restart.
+
+## Zone's filter
+It is possible to specify a filter for a distribution zone on a zone's
creation and altering.
+
+```
+CREATE ZONE "TEST_ZONE" WITH "DATA_NODES_FILTER" = '$[?(@.region == "US" &&
@.storage == "SSD")]'
+```
+```
+ALTER ZONE "TEST_ZONE" SET "DATA_NODES_FILTER " = '$..*'"
+```
+
+To express filter, JSONPath syntax is used. From the technical point of view,
to filter data nodes, we just match JSON representation of
+a node attribute with the corresponding filter.
+
+Some examples of filtering results:
+
+* Node attributes are `("region" -> "US", "storage" -> "SSD")`; the filter is
`$[?(@.region == 'US')]`; result: node pass the filter and will be included to
data nodes
+* Node attributes are `("region" -> "US")`; the filter is `$[?(@.storage ==
'SSD' && @.region == 'US')]`; result: node do not pass the filter and won't be
included to data nodes
+* Node attributes are `("region" -> "US")`; the filter is `$[?(@.storage ==
'SSD']`; result: node do not pass the filter and won't be included to data nodes
+* Node attributes are `("region" -> "US")`; the filter is `$[?(@.storage !=
'SSD']`; result: node pass the filter and will be included to data nodes
+* Node attributes are `("region" -> "US", "dataRegionSize: 10)`; the filter is
`$[?(@.region == 'EU' || @.dataRegionSize > 5)]`; result: node pass the filter
and will be included to data nodes
+
+To check all capabilities of JSONPath, see
https://github.com/json-path/JsonPath
+
+Note that as a default value for filter '$..*' filter is used, meaning that
all nodes match the filter.
+Also it is important, that if there are no specified attributes for a node, it
means that a node match only the default filter.
+
+
+
