Retrieves node or edge entities from an existing graph, with pagination support via offset and limit. Use GPUdb.show_graph() to obtain the total number of nodes and edges.
Parameters
Name of the graph from which to retrieve entities.
Starting index of the entities to retrieve (0-based). The default value is 0.
Number of entities to retrieve starting from input parameter offset. A value of -1 returns all entities from the offset to the end. Note: the output parameter entities_int or output parameter entities_string array size will be 2x this value for nodes (stride 2) or 4x for edges (stride 4). The default value is 10000.
Optional parameters. Allowed keys are:
entity_type – The type of entity to retrieve. Allowed values are:
edge – Retrieve edge entities (default).
node – Retrieve node entities.
The default value is ‘edge’.
server_id – Indicates which graph server to send the request to. Required when the graph is distributed across multiple servers. The default value is ‘0’.
concise_edge_connectivity – When true, edges are emitted in a compact connectivity form regardless of the graph’s identifier type: Output parameter entities_int contains stride-4 records [edge_id, node1_index, node2_index, edge_label_index] where node1_index/node2_index are 0-based positions into the node array (obtained from a node-entity call on the same graph). When requesting nodes with this option, the response includes tombstoned (deleted) slots in order to keep position indices stable so edge indices resolve correctly; deleted slots carry id=0 for integer graphs or an empty identifier for string/WKT graphs. For paginated node calls, subtract input parameter offset from an edge endpoint index to locate it within the returned page. Allowed values are:
true – Compact integer connectivity for edges; deleted node slots included in node output.
false – Default: edges emit node identifiers (int/string/WKT) matching the graph; deleted nodes are skipped.
The default value is ‘false’.
include_weights – When true and input parameter options entity_type is ‘edge’, the response output parameter entities_weight array is populated with one float weight per emitted edge (aligned 1:1 with the edge records in output parameter entities_int or output parameter entities_string). Empty when the graph has no weights component or when requesting nodes. Allowed values are:
true – Populate output parameter entities_weight with per-edge weights (edge requests only).
false – Default: Output parameter entities_weight is empty.
The default value is ‘false’.
The default value is an empty dict ( ).
Returns
A dict with the following entries–
Indicates a successful retrieval.
Flat array of entity data for integer-identifier graphs with a repeating stride. For node entities (stride 2): [node_id, label_index, …]. For edge entities (stride 4): [edge_id, node1_id, node2_id, label_index, …]. Populated when the graph uses integer identifiers; empty otherwise. The label_index is a 1-based index into the output parameter labels array; 0 indicates no label. When the request option ‘concise_edge_connectivity’ is ‘true’, this array is also used (regardless of graph identifier type) for edge entities and carries [edge_id, node1_index, node2_index, edge_label_index] where node1_index/node2_index are 0-based positions into the node array returned from a paired node call on the same graph.
Flat array of entity data for name-identifier (string) graphs only. For node entities (stride 2): [node_name, label_index, …]. For edge entities (stride 4): [edge_id, node1_name, node2_name, label_index, …]. Populated only when the graph uses string identifiers. Empty for integer-identifier graphs (data goes to output parameter entities_int) and for WKT/geo-XY graphs (data always goes to output parameter entities_double — ‘POINT(x y)’ strings are never emitted). The label_index is a string representation of a 1-based index into the output parameter labels array; ‘0’ indicates no label.
Compact double-packed payload for WKT (geo/XY) graphs. WKT graphs ALWAYS use this array — ‘POINT(x y)’ strings are never emitted anywhere. Stride 3 for nodes: [x, y, label_index, …]. Stride 6 for edges (non-concise): [edge_id, x0, y0, x1, y1, label_index, …]. Empty for non-WKT graphs and when concise mode emits edges into output parameter entities_int instead. label_index/edge_id occupy double slots (representable exactly up to 2^53). When ‘concise_edge_connectivity’ is ‘true’ and entity_type is ‘node’, tombstoned (deleted) WKT slots emit [0.0, 0.0, 0.0] to keep position indices stable. Roughly 4x smaller on the wire than ‘POINT(x y)’ strings and avoids any client-side regex parse.
Per-edge weight values, populated only when the request option ‘include_weights’ is ‘true’ and input parameter options entity_type is ‘edge’. Stride 1, aligned 1:1 with the edge records emitted in output parameter entities_int or output parameter entities_string (i.e. the i-th weight corresponds to the i-th edge record). Empty when the graph has no weights component, when requesting nodes, or when the option is not set. Single-precision float matches the graph server’s native weight storage.
Array of distinct label strings. The label_index values in output parameter entities_int, output parameter entities_string, or output parameter entities_double are 1-based indexes into this array; index 0 means no label.
Additional information map. Contains the following keys: ‘identifier_type’ — describes the graph’s native node identifier type: ‘int’, ‘string’, or ‘wkt’ (geo/XY graph). ‘payload_type’ — describes which array actually holds this response payload: ‘int’ (output parameter entities_int), ‘string’ (output parameter entities_string), or ‘double’ (output parameter entities_double). WKT graphs ALWAYS use ‘double’ for both nodes and edges — ‘POINT(x y)’ strings are never emitted. In concise edge mode payload_type is ‘int’ regardless of graph type. Clients should dispatch on ‘payload_type’, not ‘identifier_type’, to parse the response. ‘total_count’ — total number of entities available in the graph for the requested entity_type, used for pagination; this is the live (non-deleted) count by default, or the raw count (including deleted slots) when ‘concise_edge_connectivity’ is true for a node request. ‘status_message’ — set to ‘Cancelled’ if the request was cancelled mid-iteration (with output parameter result set to false). ‘concise_edge_connectivity’ — set to ‘true’ when the response was produced with the concise option (edges emitted as [edge_id, v0_index, v1_index, label_idx] in output parameter entities_int; WKT-graph nodes emitted as [x, y, label_idx] in output parameter entities_double; non-WKT nodes still in their native array; node output includes deleted slots to keep indices stable). ‘include_weights’ — set to ‘true’ when output parameter entities_weight is populated.