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.

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.
    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
    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 24 days ago