Inserting Span and Arrow Label into Document

In Span Labeling, there are two types of labels you can use:

  • Span label: A label applied directly to a span of tokens.

  • Arrow label: A label that connects one span label to another.

In the example below, we’ll add two span labels and one arrow label.

Mutation: UpdateLabels.

cURL

Use the following cURL command to add labels to your project. Copy and paste it, then replace the following:

  • access_token with your own API access token.

  • document-id with the ID of the document.

  • signature with the signature of the document.

  • labels that you would like to apply.

curl --location --request POST '<https://app.datasaur.ai/graphql>' \\
  --header 'Authorization: Bearer access_token' \\
  --header 'Content-Type: application/json' \\
  --data-raw '{
    "operationName": "UpdateLabels",
    "variables": {
      "input": {
        "documentId": "document-id",
        "signature": "signature",
        "labels": [
          {
            "id": "SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined",
            "l": "novel",
            "start": {
              "sentenceId": 0,
              "tokenId": 0,
              "charId": 0
            },
            "end": {
              "sentenceId": 0,
              "tokenId": 2,
              "charId": 5
            },
            "layer": 0,
            "deleted": false
          },
          {
            "id": "SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined",
            "l": "male",
            "start": {
              "sentenceId": 0,
              "tokenId": 14,
              "charId": 0
            },
            "end": {
              "sentenceId": 0,
              "tokenId": 18,
              "charId": 6
            },
            "layer": 0,
            "deleted": false
          },
          {
            "id": "ARROW:author:1:0:0:0:0:0:0:18:6:0:SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined:SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined",
            "l": "author",
            "start": {
              "sentenceId": 0,
              "tokenId": 0,
              "charId": 0
            },
            "end": {
              "sentenceId": 0,
              "tokenId": 18,
              "charId": 6
            },
            "layer": 1,
            "deleted": false
          }
        ],
        "action": "LABEL"
      }
    },
    "query": "mutation UpdateLabels($input: UpdateTokenLabelsInput!) { updateLabelsResult: updateLabels(input: $input) { updatedSentences { id } } }"
  }'

Here’s the same request in a more readable format:

{
    "operationName": "UpdateLabels",
    "variables": {
        "input": {
            "documentId": "document-id",
            "signature": "signature",
            "labels": [
                {
                    "id": "SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined",
                    "l": "novel",
                    "start": {
                        "sentenceId": 0,
                        "tokenId": 0,
                        "charId": 0
                    },
                    "end": {
                        "sentenceId": 0,
                        "tokenId": 2,
                        "charId": 5
                    },
                    "layer": 0,
                    "deleted": false
                },
                {
                    "id": "SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined",
                    "l": "male",
                    "start": {
                        "sentenceId": 0,
                        "tokenId": 14,
                        "charId": 0
                    },
                    "end": {
                        "sentenceId": 0,
                        "tokenId": 18,
                        "charId": 6
                    },
                    "layer": 0,
                    "deleted": false
                },
                {
                    "id": "ARROW:author:1:0:0:0:0:0:0:18:6:0:SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined:SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined",
                    "l": "author",
                    "start": {
                        "sentenceId": 0,
                        "tokenId": 0,
                        "charId": 0
                    },
                    "end": {
                        "sentenceId": 0,
                        "tokenId": 18,
                        "charId": 6
                    },
                    "layer": 1,
                    "deleted": false
                }
            ],
            "action": "LABEL"
        }
    },
    "query": "mutation UpdateLabels($input: UpdateTokenLabelsInput!) { updateLabelsResult: updateLabels(input: $input) { updatedSentences { id } } }"
}

The request above will produce span and arrow labels like the following:

  • operationName: you can fill any alphanumeric string in as the operationName. Refer this page for best practices on choosing an operationName .

  • variables:

    • input:

      • documentId: string, ID of the targeted document where the label will be inserted.

      • signature: hash of the document to ensure the structure of the sentence / spans of the document has not changed when inserting label. You can obtain the signature value by following the instruction in this page.

      • labels:

        • id: the unique identifier of a label.

          1. Span labels — Used to highlight text.

            • Span label IDs has 14 segments.

            • Example:

              SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined
            • Here’s what each part means:

              • SPAN → the label type

              • male → the label name / id

              • 0 → the label set layer

              • 0:0:14:0 → starting position (sentence, cellIndex, token, character)

              • 0:0:18:6 → ending position (sentence, cellIndex, token, character)

              • 0 → index

              • undefined:undefined → reserved fields used internally by the system

          2. Arrow labels — Connect one span label to another.

            • Arrow label IDs has 40 segments.

            • Example:

              ARROW:author:1:0:0:0:0:0:0:18:6:0:SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined:SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined 
            • Here’s what each part means:

              • ARROW → the label type

              • author → the arrow label name / id

              • 1 → the arrow layer

              • 0:0:0:0 → arrow starting position (sentence, cellIndex, token, character)

              • 0:0:18:6 → arrow ending position (sentence, cellIndex, token, character)

              • 0 → index

              • SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined → origin span label

              • SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined → destination span label

        • layer: indicates the index of the label set.

        • l: the label set item ID of the label set. You can obtain the label set information of a project including the label set item ID in this page.

        • start:

          • sentenceId: starting line of the label

          • tokenId: starting token of the label

          • charId: starting character index of the label

        • end:

          • sentenceId: ending line of the label

          • tokenId: ending token of the label

          • charId: ending character index of the label

        • deleted: boolean, set true if you want to delete the existing labelquery: Copy this from the example above.

  • query: Copy this from the example above.

A tag has the same meaning as label. In the near future, we will update the GraphQL Schema to refer to all instances as labels.

Response

Here is the response you can expect after issuing the cURL command. Use the id to create the project.

{
    "data": {
        "updateLabelsResult": {
            "updatedSentences": [
                {
                    "id": 0
                }
            ]
        }
    },
    "extensions": {}
}

Last updated