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.
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 typemale
→ the label name / id0
→ the label set layer0:0:14:0
→ starting position (sentence, cellIndex, token, character)0:0:18:6
→ ending position (sentence, cellIndex, token, character)0
→ indexundefined: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 typeauthor
→ the arrow label name / id1
→ the arrow layer0:0:0:0
→ arrow starting position (sentence, cellIndex, token, character)0:0:18:6
→ arrow ending position (sentence, cellIndex, token, character)0
→ indexSPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined
→ origin span labelSPAN: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.
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