Skip to content
Developer Edition runs on one host and does not require a product license file. Need multi-host deployment or performance testing at scale? Explore Enterprise Edition

SAMPLE clause

The SAMPLE clause samples a subset of edges during traversal. It is useful for analyzing superlarge datasets by working with a smaller, manageable sample.

Depending on the direction of traversal, the SAMPLE clause can be classified into two types: SAMPLE RIGHT and SAMPLE LEFT. Currently, only SAMPLE RIGHT is supported.

In persistent graphs in NebulaGraph Database Developer Edition, the SAMPLE clause is used directly in edge patterns within the MATCH statement.

Usage notes

  • The SAMPLE clause is not supported in temporary graphs.
  • The SAMPLE clause can be used only on edge patterns, not on node patterns.
  • The SAMPLE clause cannot be used in ANN search queries involving edge matching. For more information, see Nearest neighbor query.
  • Sampling is not supported if undirected edge types are inferred. The direction declaration of an undirected edge type is ~[ edge_pattern_filler ]~. For more information, see CREATE GRAPH TYPE.

How it works

The SAMPLE clause must be specified as a component of the edge pattern filler within a full edge pattern. If both the WHERE clause and the SAMPLE clause are specified in an edge pattern filler, the SAMPLE clause must appear before the WHERE clause. Sampling is performed before the filter conditions in the WHERE clause are applied. For more information about the order of components in an edge pattern filler, see Full edge pattern.

The sampling targets are the edges matched by the full edge pattern that contains the SAMPLE clause.

Rightward sampling means sampling the edges to the right of the anchor point, where the anchor point is the starting point of the traversal. For example, in the edge pattern (v1)<-[e SAMPLE RIGHT]->{1,2}(v2), v1 is the anchor point.

Sampling behavior is determined by the sampling context, which consists of the following four components:

  • The anchor point
  • The edge type of the edges connected to the anchor point
  • The direction of the edges connected to the anchor point
  • Each hop of the edge pattern

During traversal, different sampling contexts are independent of each other. For each sampling context, edges are sampled based on the specified sampling method and sample size.

Syntax

sample_clause
SAMPLE RIGHT sampling_method sample_size
sampling_method
FIRST_FETCH RANDOM UNIQUE_NEIGHBOR UNQ_NBR
sample_size
unsigned_integer % 

sample_clause ::=
    'SAMPLE' 'RIGHT'? sampling_method? sample_size

sampling_method ::=
    'FIRST_FETCH' | 'RANDOM' | 'UNIQUE_NEIGHBOR' | 'UNQ_NBR'

sample_size ::=
    unsigned_integer '%'?

Parameters

An optional keyword that specifies the traversal direction for sampling. Currently, only rightward sampling is supported.

If this keyword is not specified, the default is rightward sampling.

sampling_method

The sampling method to use for each sampling context. Valid values include:

  • FIRST_FETCH: Sample the first N edges. This is the default.
  • RANDOM: Randomly sample edges.
  • UNIQUE_NEIGHBOR or UNQ_NBR: Randomly sample edges connected to unique neighbors. Parallel edges connecting the same pair of nodes are deduplicated before sampling.

sample_size

The sample size for each sampling context. The following two formats are supported:

  • An unsigned integer representing the maximum number of samples. In this case, the unsigned integer must be a positive integer.
  • An unsigned integer followed by a percent sign (%), representing a sampling percentage. In this case, the unsigned integer must be in the range [0, 100]. If the calculated result is a decimal, it is rounded up.

Examples

The following examples are based on the Example dataset.

Sample the first 2 edges

'''
USE movie
MATCH (v1{id: 18})<-[e SAMPLE RIGHT FIRST_FETCH 2 ]-(v2) 
RETURN labels(v1) AS anchor_labels,
       v1.id AS anchor_business_id,
       type(e) AS edge_type,
       count(*) AS sampled_count
'''

Return:

+---------------+--------------------+-----------+---------------+
| anchor_labels | anchor_business_id | edge_type | sampled_count |
+---------------+--------------------+-----------+---------------+
| [Genre]       | 18                 | WithGenre | 2             |
| [Movie]       | 18                 | Direct    | 1             |
| [Movie]       | 18                 | Act       | 2             |
+---------------+--------------------+-----------+---------------+

The preceding return shows there are 3 sampling contexts as follows:

  1. For the anchor node with label Movie and business property id set to 18, two edges of edge type Act are sampled.
  2. For the anchor node with label Movie and business property id set to 18, one edge of edge type Direct is sampled since only one such edge exists in the dataset.
  3. For the anchor node with label Genre and business property id set to 18, two edges of edge type WithGenre are sampled.

Randomly sample 10% edges

'''
USE movie
MATCH (v1{id: 18})<-[e SAMPLE RIGHT RANDOM 10% ]->(v2)
RETURN labels(v1) AS anchor_labels,
       v1.id AS anchor_business_id,
       type(e) AS edge_type,
       count(*) AS sampled_count
'''

Return:

+---------------+--------------------+-----------+---------------+
| anchor_labels | anchor_business_id | edge_type | sampled_count |
+---------------+--------------------+-----------+---------------+
| [Movie]       | 18                 | WithGenre | 2             |
| [Genre]       | 18                 | WithGenre | 3             |
| [Person]      | 18                 | Watch     | 3             |
| [Movie]       | 18                 | Direct    | 1             |
| [Movie]       | 18                 | Act       | 5             |
+---------------+--------------------+-----------+---------------+

The preceding return shows there are 5 sampling contexts as follows:

  1. For the anchor node with label Movie and business property id set to 18, five edges of edge type Act are sampled. There are a total of 44 edges of this type, and 10% of 44 is rounded up to 5.
  2. For the anchor node with label Movie and business property id set to 18, one edge of edge type Direct is sampled.
  3. For the anchor node with label Movie and business property id set to 18, two edges of edge type WithGenre are sampled.
  4. For the anchor node with label Person and business property id set to 18, three edges of edge type Watch are sampled.
  5. For the anchor node with label Genre and business property id set to 18, three edges of edge type WithGenre are sampled.

Randomly sample 2 edges connecting unique neighboring nodes

'''
USE movie 
MATCH p = (v1@Genre{id: 18})<-[e SAMPLE RIGHT UNIQUE_NEIGHBOR 2]-{1,2}(v2)
RETURN length(p) AS hops,
       transform(nodes(p), n -> n.id) AS node_business_ids,
       transform(e, edge -> type(edge)) AS edge_types
'''

Example return:

+------+-------------------+--------------------+
| hops | node_business_ids | edge_types         |
+------+-------------------+--------------------+
| 1    | [18,346]          | [WithGenre]        |
| 1    | [18,601]          | [WithGenre]        |
| 2    | [18,346,20831]    | [WithGenre,Act]    |
| 2    | [18,601,330]      | [WithGenre,Watch]  |
| 2    | [18,346,5026]     | [WithGenre,Direct] |
| 2    | [18,601,23764]    | [WithGenre,Act]    |
| 2    | [18,346,339]      | [WithGenre,Watch]  |
| 2    | [18,346,7457]     | [WithGenre,Act]    |
| 2    | [18,346,603]      | [WithGenre,Watch]  |
| 2    | [18,601,488]      | [WithGenre,Direct] |
| 2    | [18,601,9981]     | [WithGenre,Act]    |
| 2    | [18,601,580]      | [WithGenre,Watch]  |
+------+-------------------+--------------------+

The preceding return shows there are 7 sampling contexts as follows:

  1. Starting from the Genre anchor node whose business property id is 18, the first hop samples two WithGenre edges connected to two Movie nodes whose business property id values are 346 and 601.
  2. From the Movie node whose business property id is 346, the second hop:
    1. two edges of edge type Act are sampled, each connecting a unique neighboring node.
    2. one edge of edge type Direct is sampled.
    3. two edges of edge type Watch are sampled, each connecting a unique neighboring node.
  3. From the Movie node whose business property id is 601, the second hop:
    1. two edges of edge type Act are sampled, each connecting a unique neighboring node.
    2. one edge of edge type Direct is sampled.
    3. two edges of edge type Watch are sampled, each connecting a unique neighboring node.

The sample size 2 applies separately to each sampling context; it does not limit the entire query to two edges. Since no parallel edges exist in the example dataset, all sampled edges connect unique neighboring nodes. The specific random sample may differ between executions.