REST API Documentation: Upload API 2.0

Overview

In Graphistry's Upload API, the inclusion and exclusion logic allows users to control field visibility at both global and type-specific levels. Users can now define which fields are shown or hidden for specific types (e.g., client vs. server nodes) within each label type (point or edge), enabling even more customized and focused visualizations.

Enhanced Field Management for Inspectors: Control over field inclusions ("only show fields x, y, z") and exclusions ("show everything EXCEPT x, y, z").
Advanced Field Control Options: Toggle null field visibility in entity inspectors.

Concepts

The complex encodings section of a create dataset can include options for controlling field visibility in your dataset using inclusion and exclusion. These mechanisms enable users to specify which fields to show (inclusion) and which to hide (exclusion) in the graph's labels. Currently, inclusion and exclusion logic is applied at the global level for each label type (point or edge). This means that any specified inclusion or exclusion rules will apply to all labels of that type across the dataset. Users can manually simulate this behavior by carefully setting up the inclusion/exclusion rules for different graph types, but it will still apply globally to all labels of the specified type.

Inclusion: Only the specified fields or attributes are displayed in the label.
Exclusion: All fields are shown in the label except for the specified fields or attributes.

Type-specific rules: Inclusion and exclusion logic can now be defined for specific types within each label type. For example, you can specify unique field visibility rules for "client" and "server" types under the "point" label type. This allows for control over which attributes are displayed for each specific type.

When type-specific rules are defined, they take precedence over global rules for the specified type. Global inclusion and exclusion rules apply only if no type-specific rules are provided or as a fallback for other types.

Point field inclusion

Control which fields are shown for certain nodes in the graph by including specific attributes. For instance, you may want to display only the "Server" type field for certain nodes. The inclusion logic allows you to specify which fields to display in the label, making the visualization more focused.


curl -X POST https://hub.graphistry.com/api/v2/upload/datasets/ \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
  "node_encodings": {
    "bindings": {
      "node": "nodeId"
    },
    "complex": {
      "default": {
        "pointFieldInclusionEncoding": {
          "graphType": "point",
          "encodingType": "fieldinclusion",
          "attribute": "type",
          },
          "inclusion": {
            "Server": true,
            "Client": false
          }
        }
      }
    }
 }

Exclusion logic for edge filtering

Control which fields are displayed in the edge label by excluding specific attributes. For instance, you may want to hide details like the line count for certain edges between computers. This logic ensures those specific fields are not shown in the label, making the displayed information more relevant and concise.


curl -X POST https://hub.graphistry.com/api/v2/upload/datasets/ \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
  "edge_encodings": {
    "bindings": {
      "source": "src_computer",
      "destination": "dst_computer"
    },
    "complex": {
      "default": {
        "edgeFieldExclusionEncoding": {
          "graphType": "edge",
          "encodingType": "fieldexclusion",
          "attribute": "linecount",
          "exclusion": {
            "linecount": true,
            "duration": true,
            "timestamp": true
          }
        }
      }
    }
  }
}

Type-specific field inclusion for points

You can define inclusion rules for specific types within point labels, such as "client" and "server," to control which fields are shown in the visualization. Here’s how to display only the "name" field for "client" points and the "cpu" and "ram" fields for "server" points.


curl -X POST https://hub.graphistry.com/api/v2/upload/datasets/ \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
  "node_encodings": {
    "bindings": {
      "node": "nodeId"
    },
    "complex": {
      "default": {
        "pointFieldInclusionEncoding": {
          "graphType": "point",
          "encodingType": "fieldinclusion",
          "inclusion": {
            "types": {
              "client": { "name": true, "email": false },
              "server": { "cpu": true, "ram": true, "status": false }
            }
          }
        }
      }
    }
  }
}

Combined inclusion and exclusion logic

You may need to combine inclusion and exclusion logic to control which fields are shown or hidden for nodes and edges. For example, you could choose to include only the "type" field for nodes with "type = Server" while excluding the "line count" field for edges between servers. This allows for complex field-level filtering scenarios to customize the visualization.