Examples

Basic queries

The full protocol state can be extracted via GraphQL:

{
  protocolStates {
    nodes {
      protocolId
      protoRefId
      frame
      currentState
      version
      commandId
      created
    }
  }
}

The data can be filtered in various ways. Below, we're filtering out all protocols besides those that match the two provided protocolIds.

{
  protocolStates(
    filter: { protocolId: { in: ["0aa0fe24-a5e8-4e46-b6cd-daf311430102", "1d3fe2e9-2f61-4ba8-9146-03b73d9982a0"] } }
  ) {
    nodes {
      protocolId
      protoRefId
      frame
      currentState
      version
      commandId
      created
    }
  }
}

Some examples of how to apply filters to queries can be found here.

When we are querying columns that are foreign keys, we can also directly perform joins (or in GraphQL terms, traverse the connection) with the corresponding tables. For example, we could join the above query of the protocolStatesV2 table with the commands table:

{
  protocolStates {
    nodes {
      protocolId
      protoRefId
      frame
      currentState
      version
      created
      command {
        sequence
        action
        discriminator
      }
    }
  }
}

Querying protocol fields

Special tables have been added for protocol fields. Here is an example of how we would query for all the number fields named n in the system that are greater than 2. We also traverse the connection ( perform a join) to the protocolStatesV2 table, and from there to the protocolStatesParties table in order to retrieve the parties of the protocol in question. As before, we also traverse the connection to the commands table.

Filtering and traversal

{
  protocolFieldsNumbers(filter: { and: { field: { equalTo: "n" }, value: { greaterThan: "2" } } }) {
    nodes {
      field
      value
      protocol {
        protoRefId
        protocolId
        currentState
        protocolStatesPartiesByProtocolId {
          nodes {
            party
          }
        }
        command {
          sequence
          arguments
        }
      }
    }
  }
}

Types

All the basic NPL types can be queried. In some cases, such as with DateTime, there are extra columns that you probably want to include in your query. The GraphiQL web interface makes this easy with its type documentation and autocompletion features.

{
  protocolFieldsDatetimes {
    nodes {
      protocolId
      field
      value
      zoneId
    }
  }
}

With DateTime you can also do temporal filtering (this also works with LocalDate).

{
  protocolFieldsDatetimes(
    filter: {
      protocolId: { notIn: ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"] }
      value: { greaterThan: "2021-09-27T10:31:29.59518+00:00" }
    }
  ) {
    nodes {
      protocolId
      field
      value
      zoneId
    }
  }
}

You don't have to start your query with the field table of the type in question. You can just as easily traverse the graph from another connected table:

{
  protocolStates {
    nodes {
      protocolId
      protocolFieldsDatetimesByProtocolId {
        nodes {
          field
          value
          zoneId
        }
      }
    }
  }
}

Graph traversal

There are several places where we can traverse the graph representation of the Postgres tables, but the tables where this is likely to occur most frequently are probably ProtocolFieldsProtocol, ProtocolFieldsCollectionsProtocol, and StructFieldsProtocol. These tables describe protocol fields that contain references to other protocols. One can keep traversing these connections for as long as one likes -- but please keep in mind that very deep queries are likely to be computationally expensive.

A query with multiple traversals might look something like this:

{
  protocolStates {
    nodes {
      protocolFieldsProtocolsByProtocolId {
        nodes {
          protocolId
          field
          value
          protocol {
            protoRefId
            protocolFieldsProtocolsByProtocolId {
              nodes {
                field
                value
              }
            }
            protocolFieldsBlobsByProtocolId {
              nodes {
                field
                value
              }
            }
          }
        }
      }
      protocolFieldsCollectionsProtocolsByValue {
        nodes {
          field
          key
          value
          collectionType
          protocol {
            protocolId
            protoRefId
            protocolFieldsDatetimesByProtocolId {
              nodes {
                field
                value
              }
            }
          }
        }
      }
    }
  }
}