Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/clauses/sample/ Documentation version: v5.3.2 # 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/nearest-neighbor/). - 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/graph-type/create/). ## 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/clauses/where/) 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/edge-patterns/#_2). 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 Syntax diagramSource sample_clause sampling_method sample_size ```` sample_clause ::= 'SAMPLE' 'RIGHT'? sampling_method? sample_size sampling_method ::= 'FIRST_FETCH' | 'RANDOM' | 'UNIQUE_NEIGHBOR' | 'UNQ_NBR' sample_size ::= unsigned_integer '%'? ```` ## Parameters ### `RIGHT` 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/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.