Skip to content

Latest commit

 

History

History
1062 lines (891 loc) · 38.1 KB

write_operations.md

File metadata and controls

1062 lines (891 loc) · 38.1 KB
Raw

Write operations

Those command modify Wikibase so you will need to first setup credentials to use them: you will get a prompt requesting those credentials when required, but if you want to setup those credentials ahead, you can run wb config credentials https://www.wikidata.org test (Replace https://www.wikidata.org by your Wikibase instance url if necessary). For more documentation on the different options to setup credentials, see wikibase-edit single-user credentials setup (wikibase-edit is the lib on which wikibase-cli relies for all write operations).

Those credentials will be saved in clear text (Run wb config path to know where). This allows not having to re-enter credentials everytimes, but it can problematic on a non-personal computer: in such a case, make sure to run wb config clear once you're done.

The following documentation often assumes that the Wikibase instance we work with is Wikidata (using the wd command, which is just an alias of the wb command bound to Wikidata config), unless specified otherwise (using the wb command and custom instance host (-i) and SPARQL endpoint (-e).

Summary

labels

See Wikidata:Glossary#Label

wb set-label

Set a label on an entity in a given language

wb set-label <entity> <language> <label>
# Alias:
wb sl <entity> <language> <label>

Example:

# Set the label 'lorem ipsum' to the item Q4115189 in French
wb set-label Q4115189 fr "lorem ipsum"

For more advanced use cases (such as setting multiple labels on a single entity at once) you should rather use edit-entity.

wb remove-label

Remove a label on an entity in a given language

wb remove-label <entity> <language>
# Alias:
wb rl <entity> <language>

Example:

# Remove Q4115189 French label
wb remove-label Q4115189 fr

descriptions

See Wikidata:Glossary#Description

wb set-description

Set a description on an entity in a given language

wb set-description <entity> <language> <description>
# Alias:
wb sd <entity> <language> <description>

Examples:

# Set the description "lorem ipsum" to the item Q4115189 in French
wb set-description Q4115189 fr "lorem ipsum"

For more advanced use cases (such as setting multiple descriptions on a single entity at once) you should rather use edit-entity.

wb remove-description

Remove a description on an entity in a given language

wb remove-description <entity> <language>
# Alias:
wb rd <entity> <language>

Example:

# Remove Q4115189 French description
wb remove-description Q4115189 fr

aliases

See Wikidata:Glossary#Alias

wb add-alias

Add one or several aliases to the list of aliases of an entity in a given language

wb add-alias <entity> <language> <alias>
# Alias:
wb aa <entity> <language> <alias>
# Add an alias
wb add-alias Q4115189 fr foo
# Add several aliases separated by a pipe
wb add-alias Q4115189 fr "foo|bar"

For more advanced use cases, you should rather use edit-entity.

wb remove-alias

Remove one or several aliases from the list of aliases of an entity in a given language

wb remove-alias <entity> <language> <alias>
# Alias:
wb ra <entity> <language> <alias>
# Remove an alias
wb remove-alias Q4115189 fr foo
# Remove several aliases separated by a pipe
wb remove-alias Q4115189 fr "foo|bar"

For more advanced use cases, you should rather use edit-entity.

wb set-alias

Set the list of aliases of an entity in a given language

wb set-alias <entity> <language> <alias>
# Alias:
wb sa <entity> <language> <alias>
# Replace all Q4115189's French alias by 'foo'
wb set-alias Q4115189 fr foo
# Replace all Q4115189's French alias by 'foo' and 'bar'
wb set-alias Q4115189 fr "foo|bar"

For more advanced use cases, you should rather use edit-entity.

claims

See Wikidata:Glossary#Claim

wb add-claim

Add a claim to an entity.
Alternative: QuickStatements

wb add-claim <entity> <property> <value>
# Alias:
wb ac <entity> <property> <value>

Options:

  • --rank <preferred|deprecated>: set the claim rank

Examples:

# Add the Twitter account (P2002) 'bulgroz' to the Sandbox (Q4115189) entity
wd add-claim Q4115189 P2002 bulgroz
# The same but using the command alias
wd ac Q4115189 P2002 bulgroz
# Add the statement that the Sandbox (Q4115189) has for part (P527) the sand (Q34679)
# with a preferred rank
wd ac Q4115189 P527 Q34679 --rank preferred

For more advanced use cases, such as adding a claim with qualifiers and references, you should rather use edit-entity.

rich values

Some values like monolingual text, quatities with a unit, or time with a precision, require to pass more data than a simple primitive value. This can be done by passing an object, either in a JSON or a query string format:

JSON format
wd ac Q4115189 P1476 '{"text":"bac à sable","language":"fr"}'
wd ac Q4115189 P1106 '{"amount":123,"unit":"Q4916"}'
# On precision and calendar, see wikibase-edit documentation https://github.com/maxlath/wikibase-edit/blob/master/docs/how_to.md#time
wd ac Q4115189 P578 '{"time":"1800","precision":7,"calendar":"julian"}'
# Set a coordinate on another celestial body than Earth (here, Mars (Q111))
wd ac Q4115189 P626 '{ "latitude": 18.65, "longitude": 226.2, "precision": 0.01, "globe": "http://www.wikidata.org/entity/Q111" }'
query string format
wd ac Q4115189 P1476 'text=bac à sable&language=fr'
wd ac Q4115189 P1106 'amount=123&unit=Q4916'
wd ac Q4115189 P578 'time=1800&precision=7'
with a reference

Workflow example to add a claim with a reference, using jq. See wb add-reference for more details.

claim_guid=$(wd add-claim Q4115189 P369 Q34679 | jq -r .claim.id)
# Add the reference that this claim is imported from (P143) Wikipedia in Uyghur (Q60856)
wd add-reference $claim_guid P143 Q60856
special claim snaktypes

You can add novalue and somevalue claims by passing the desired snaktype in a JSON object as values:

wd ac Q4115189 P1106 '{"snaktype":"novalue"}'
wd ac Q4115189 P1106 '{"snaktype":"somevalue"}'

wb update-claim

Update a claim value while keeping its qualifiers and references

wb update-claim <entity-id> <property> <old-value> <new-value>
# OR
wb update-claim <guid> <new-value>
# Alias:
wb uc <entity-id> <property> <old-value> <new-value>
wb uc <guid>

Options:

  • --rank <normal|preferred|deprecated>: set the claim rank

Examples:

# Change the the Sandbox (Q4115189) Twitter account (P2002) from 'Zorglub' to 'Bulgroz'
wd update-claim Q4115189 P2002 Zorglub Bulgroz
# or using the claim's guid
wd uc 'Q4115189$F00E22C2-AEF7-4145-A743-2AB6292ABFA3' Bulgroz
# Update both the claim rank and value
wd uc 'Q4115189$F00E22C2-AEF7-4145-A743-2AB6292ABFA3' Bulgroz --rank preferred
# Only update the rank
wd uc 'Q4115189$F00E22C2-AEF7-4145-A743-2AB6292ABFA3' --rank preferred
# This can also be written using the object interface
wb uc '{ "guid": "Q4115189$F00E22C2-AEF7-4145-A743-2AB6292ABFA3", "rank": "preferred" }'

# Change a coordinate from Mars (Q112) to Venus (Q313)
wd uc Q4115189 P626 '{ "latitude": 18.65, "longitude": 226.2, "precision": 0.01, "globe": "http://www.wikidata.org/entity/Q111" }' '{ "latitude": 18.65, "longitude": 226.2, "precision": 0.01, "globe": "http://www.wikidata.org/entity/Q313" }'
# or using the claim's guid: that's generally the preferred way to do it
wd uc 'Q4115189$F00E22C2-AEF7-4145-A743-2AB6292ABFA3' '{ "latitude": 18.65, "longitude": 226.2, "precision": 0.01, "globe": "http://www.wikidata.org/entity/Q313" }'
update claim in batch mode

Arguments can either be passed in object mode

echo '
{ "guid": "Q1$d941fe74-4a76-a143-6766-a24d2ef2ddad", "newValue": "foo", "rank": "preferred" }
{ "guid": "Q1$63ef3ef4-4499-110a-3f66-33b352b61520", "newValue": "bar" }
{ "guid": "Q1$aaa3162d-4faa-6761-a8e6-f5e6a639afd5", "rank": "deprecated" }
{ "guid": "Q1$b1a0d905-4f20-065d-4aa7-787ea29c5af1", "rank": "normal" }
' | wb uc -b

or as inline values (but then you can't set the rank)

echo '
Q1$d941fe74-4a76-a143-6766-a24d2ef2ddad foo
Q1$63ef3ef4-4499-110a-3f66-33b352b61520 bar
' | wb uc -b

wb move-claim

Move claims from an entity to another and/or from a property to another

wb move-claim <guid|property-claims-id> <target-entity-id> <target-property-id>
# Alias
wb mc <guid|property-claims-id> <target-entity-id> <target-property-id>

Examples:

Q4115189_P19_claim_guid='Q4115189$13681798-47F7-4D51-B3B4-BA8C7E044E1F'

# change the property of a claim (without changing entity)
wb mc $Q4115189_P19_claim_guid Q4115189 P20
# move the claim to another entity (without changing the property)
wb mc $Q4115189_P19_claim_guid Q13406268 P19
# move the claim to another entity and another property
wb mc $Q4115189_P19_claim_guid Q13406268 P20

# move all Q4115189 P19 claims to P20 (without changing entity)'
wb mc Q4115189#P19 Q4115189 P20
# move all Q4115189 P19 claims to Q13406268 (without changing the property)'
wb mc Q4115189#P19 Q13406268 P19
# move all Q4115189 P19 claims to Q13406268 P20'
wb mc Q4115189#P19 Q13406268 P20

Certain claims can be moved between properties of different datatypes, see wikibase-edit documentation

wb remove-claim

Remove a claim

wb remove-claim <guid>
# Alias:
wb rc <guid>

Examples:

# /!\ beware of the '$' sign that might need escaping
wd remove-claim "Q71\$BD9A4A9F-E3F9-43D4-BFDB-484984A87FD7"
# or simply
wd remove-claim 'Q71$BD9A4A9F-E3F9-43D4-BFDB-484984A87FD7'
# or several at a time (required to be claims on the same entity)
wd remove-claim 'Q71$BD9A4A9F-E3F9-43D4-BFDB-484984A87FD7' 'Q71$B8EE0BCB-A0D9-4821-A8B4-FB9E9D2B1251' 'Q71$2FCCF7DD-32BD-496C-890D-FEAD8181EEED'

qualifiers

See Wikidata:Glossary#Qualifier

wb add-qualifier

Add a qualifier to a claim

wb add-qualifier <claim-guid> <property> <value>
# Alias:
wb aq <claim-guid> <property> <value>

Examples:

claim_guid='Q4115189$E66DBC80-CCC1-4899-90D4-510C9922A04F'
# entity qualifier
wd add-qualifier $claim_guid P155 'Q13406268'

# string qualifier
wd aq $claim_guid P1545 'A-123'

# time qualifier
wd aq $claim_guid P580 '1802-02-26'

# quantity qualifier
wd aq $claim_guid P2130 123

# quantity qualifier with a unit
wd aq $claim_guid P2130 '{"amount":123,"unit":"Q4916"}'

# monolingualtext qualifier
wd aq $claim_guid P3132 "text=les sanglots long des violons de l'automne&language=fr"
special qualifier snaktypes

You can add novalue and somevalue qualifiers by passing the desired snaktype in a JSON object as values:

claim_guid='Q4115189$E66DBC80-CCC1-4899-90D4-510C9922A04F'
wd aq $claim_guid P1106 '{"snaktype":"novalue"}'
wd aq $claim_guid P1106 '{"snaktype":"somevalue"}'

wb update-qualifier

Update a qualifier from an existing value to a new value

wb update-qualifier <claim-guid> <property> <old-value> <new-value>
# Alias:
wb uq <claim-guid> <property> <old-value> <new-value>

Examples:

claim_guid='Q4115189$E66DBC80-CCC1-4899-90D4-510C9922A04F'
# entity qualifier
wd update-qualifier $claim_guid P155 'Q13406268' 'Q3576110'

# string qualifier
wd uq $claim_guid P1545 'A-123' 'B-123'

# time qualifier
wd uq $claim_guid P580 '1802-02-26' '1802-02-27'

# quantity qualifier
wd uq $claim_guid P2130 123 124

# quantity qualifier with a unit
wd uq $claim_guid P2130 'amount=123&unit=Q4916' 'amount=124&unit=Q4916'

# monolingualtext qualifier
wd uq $claim_guid P3132 'text=aaah&language=fr' 'text=ach sooo&language=de'

wb move-qualifier

Change which property a qualifier is using

wb move-qualifier <guid> [hash] <old-property-id> <new-property-id>
# Alias
wb mq <guid> [hash] <old-property-id> <new-property-id>

Examples:

claim_guid='Q4115189$E66DBC80-CCC1-4899-90D4-510C9922A04F'
# Or, if you are working from the output of a SPARQL request
claim_guid='wds:Q4115189-E66DBC80-CCC1-4899-90D4-510C9922A04F'
# Or actually any prefix
claim_guid='s:Q4115189-E66DBC80-CCC1-4899-90D4-510C9922A04F'
# Or even no prefix at all, which can be convenient to not have to deal with escaping $
claim_guid='Q4115189-E66DBC80-CCC1-4899-90D4-510C9922A04F'

# move all P2310 qualifiers of this claim to P2311
wb mq $claim_guid P2310 P2311

# move only the first P2310 qualifier to P2311
qualifier_hash=$(wb data 'Q549$3EDF7856-5BE5-445A-BC60-FB2CDDCDA44F' | jq -r '.qualifiers.P2310[0].hash')
wb mq $claim_guid $qualifier_hash P2310 P2311

Just like for move-claim, certain qualifiers can be moved between properties of different datatypes, see wikibase-edit documentation

wb remove-qualifier

wb remove-qualifier <claim-guid> <qualifiers-hashes>
# Alias:
wb rq <claim-guid> <qualifiers-hashes>

Examples:

claim_guid='Q4115189$E66DBC80-CCC1-4899-90D4-510C9922A04F'
# Or, if you are working from the output of a SPARQL request
claim_guid='wds:Q4115189-E66DBC80-CCC1-4899-90D4-510C9922A04F'
# Or actually any prefix
claim_guid='s:Q4115189-E66DBC80-CCC1-4899-90D4-510C9922A04F'
# Or even no prefix at all, which can be convenient to not have to deal with escaping $
claim_guid='Q4115189-E66DBC80-CCC1-4899-90D4-510C9922A04F'

# Remove a qualifier from this claim
wd rq $claim_guid '24aa18192de7051f81d88d1ab514826002d51c14'
# Remove several qualifiers from this claim by passing the qualifier hashes as one argument made of several pipe-separated hashes
wd rq $claim_guid '24aa18192de7051f81d88d1ab514826002d51c14|f6c14e4eebb3d4f7595f0952c1ece0a34d85368b'}

references

See Wikidata:Glossary#Reference

wb add-reference

Add a reference to an claim

add a reference with a single snak
wb add-reference <claim-guid> <property> <value>
# Alias:
wb ar <claim-guid> <property> <value>

Examples:

# Add a reference URL (P854) to this claim
# /!\ beware of the '$' sign that might need escaping
wd add-reference "Q4115189\$E66DBC80-CCC1-4899-90D4-510C9922A04F" P854 'https://example.org/rise-and-box-of-the-holy-sand-box'
# or simply
wd add-reference 'Q4115189$E66DBC80-CCC1-4899-90D4-510C9922A04F' P854 'https://example.org/rise-and-box-of-the-holy-sand-box'
# Reference the claim as imported from (P143) Wikipedia in Uyghur (Q60856)
wd add-reference 'Q4115189$E66DBC80-CCC1-4899-90D4-510C9922A04F' P143 Q60856
# or simply
wd ar 'Q4115189$E66DBC80-CCC1-4899-90D4-510C9922A04F' P143 Q60856

See add claim with a reference for a workflow example to easily get the claim guid

add a reference with multiple snaks

To create a single reference with multiple snaks we will need to use the object interface, passing the guid and snaks as a JSON object.

# That object can be passed as inline JSON
wb add-reference <JSON>
# or as a path to a JSON file
wb ar ./reference.json
# or as a path to JS file exporting an object, or exporting a JS function, which given some arguments would return an object (it can be an async function)
wb ar ./reference.js P248 P813

Example:

// reference.js: a JS file exporting an object
module.exports = {
  guid: 'Q63313825$A42967A6-CA5B-41AD-9F1F-3DAEF10DDBB5',
  snaks: {
    P248: 'Q53556514',
    P5199: '000011361',
    P813: '2019-03-06'
  }
}

Could then be passed like this

wb ar ./reference.js

In case you need to add a similar kind of reference to several claims, you might want to use a JS function instead:

// reference.js: a JS file exporting an object
module.exports = function (guid, statedIn, BLnumber) {
  const today = new Date().toISOString().split('T')[0]
  return {
    guid,
    snaks: {
      P248: statedIn,
      P5199: BLnumber,
      P813: today
    }
  }
}

Could then be passed like this

wb ar ./reference.js 'Q63313825$A42967A6-CA5B-41AD-9F1F-3DAEF10DDBB5' Q53556514 000011361

wb remove-reference

Remove a reference from a claim

wb remove-reference <claim-guid> <references-hashes>
# Alias:
wb rr <claim-guid> <references-hashes>

Examples:

# Remove a reference from this claim
wd remove-reference 'Q4115189$E51978A1-D13A-4916-800E-74ACD2466970' '72ea3cdd27062da9f0971c1feab6df32d729ecb3'
# Remove several references from this claim by passing the reference hashes as one argument made of several pipe-separated hashes
wd remove-reference 'Q4115189$E51978A1-D13A-4916-800E-74ACD2466970' '72ea3cdd27062da9f0971c1feab6df32d729ecb3|5e9840f6896948b13d6e9c6328169643229aa3db'}

sitelinks

See Wikidata:Glossary#Sitelink

wb set-sitelink

Set a sitelink on an entity for a given site

wb set-sitelink <entity-id> <site> <title> [badges]
# Alias:
wb ss <entity-id> <site> <title> [badges]

Examples:

# Link Q4115189 to the article 'The Sandbox' on the English Wikiquote
wb set-sitelink Q4115189 enwikiquote "The Sandbox"
# Also set badges for that sitelink
wb set-sitelink Q4115189 enwikiquote "The Sandbox" Q17437796,Q17437798
# To remove badges, set the sitelink again without the undesired badges
wb set-sitelink Q4115189 enwikiquote "The Sandbox"

The list of badges used on Wikidata can be found at Help:Badges

wb remove-sitelink

Remove a sitelink on an entity for a given site

wb remove-sitelink <entity-id> <site>
# Alias:
wb rs <entity-id> <site>

Example:

# Remove the link from Q4115189 to any article in the English Wikiquote
wb set-sitelink Q4115189 enwikiquote

badges

wb add-badge

Add badges on an existing sitelink, without removing other badges that might already have been set

wb add-badge <entity-id> <site> <badges>
# Alias:
wb ab <entity-id> <site> <badges>

Example:

# Add Q17437796 and Q17437798 badges on Q4115189 enwikiquote sitelink
wb add-badge Q4115189 enwikiquote Q17437796,Q17437798

wb remove-badge

Remove badges on an existing sitelink

wb remove-badge <entity-id> <site> <badges>
# Alias:
wb rb <entity-id> <site> <badges>

Example:

# Remove Q17437796 and Q17437798 badges on Q4115189 enwikiquote sitelink
wb remove-badge Q4115189 enwikiquote Q17437796,Q17437798

entity

See Wikidata:Glossary#Entity

wb create-entity

Create a new entity (currently supported types: item, property)

# Pass data as JSON
wd create-entity '{"labels":{"en":"a label","fr":"un label"},"descriptions":{"en":"some description","fr":"une description"},"claims":{"P1775":["Q3576110","Q12206942"],"P2002":"bulgroz"}}'

# Pass data as a JSON file
wb create-entity ./new_entity_data.json

# Alias:
wb ce <entity-data>

Assuming that you have the proper authorization, creating a property can as simple as:

wb create-entity '{ "datatype": "string", "labels": { "en": "some new string property" } }'

Other that the datatype and the absence of id, the create-entity command is identical to the edit-entity command.

See wikibase-edit documentation on entity.create for details on the input format.

Demos:

See also wikibase-cli create template collection for some examples.

wb edit-entity

Edit an existing item (currently supported types: item, property)

wb edit-entity <inline-entity-json|file-path>
# Alias:
wb ee <inline-entity-json|file-path>

See wikibase-edit documentation on entity.edit for details on the expected input format, especially on how to set complex values, qualifiers and references, or remove existing data. See also the section on claim reconciliation.

Pass data as inline JSON

Pass data as inline JSON.

wd edit-entity '{"id":"Q4115189", "labels":{"en":"a label","fr":"un label"},"descriptions":{"en":"some description","fr":"une description"},"claims":{"P1775":["Q3576110","Q12206942"],"P2002":"bulgroz"}, "sitelinks":{"eswiki": "Wikipedia:Wikidata/Zona de pruebas"}}'

It works, but writting JSON by hand isn't that fun, we can do better.

Pass data as a JSON file

Taking our JSON data from a file can be much more convenient than the inline option above, as it can be generated from other commands, or manually edited with the help of smart text editors that might help you with the syntax.

wb edit-entity ./existing_entity_data.json

This ./existing_entity_data.json file could be generated in different ways, but the easiest is to use the generate-template command:

wd generate-template Q4115189 --format json > Q4115189.edit-template.json
# Do your modifications, and then
wb edit-entity ./Q4115189.edit-template.json

The JSON syntax remains heavy with all those " though, if you are not generating it somehow and simply writting your data file by hand, you might be better of going with a JS file (see below).

Pass data as a static JS object file

The JavaScript object notation is very similar to JSON (thus the name of the later), but much lighter, which is very convenient when editing data manually.

wb edit-entity ./existing_entity_data.js

This ./existing_entity_data.js could be something like:

module.exports = {
  id: 'Q4115189',
  labels: {
    // Add a label
    en: 'a label',
    // Remove a label
    fr: null,
  },
  descriptions: {
    // Add a description
    en: 'some description',
    // Remove a description
    fr: null,
  },
  aliases: {
    // Set aliases in a language (will override existing aliases)
    en: [ 'an alias', 'another alias' ],
    // Remove all aliases in a language
    fr: null,
  },
  claims: {
    P123: 'Q1799264',
    P369: [
      'Q13406268',
      {
        value: 'Q1992907',
        qualifiers: {
          P370: 'some qualifier value'
        },
        references: [
          { P370: 'some reference value', P813: '2022-10-28' },
          { P370: 'another reference value', P813: '2022-10-28' },
        ]
      },
    ]
  },
  sitelinks: {
    // Set a sitelink without badges
    eswiki: 'Wikipedia:Wikidata/Zona de pruebas',
    // Set a sitelink with badges
    zhwikisource: {
      title: 'Wikisource:维基数据/沙盒',
      badges: [ 'Q17437796', 'Q17437798' ],
    },
    // Delete the sitelink
    frwikiquote: null
  },
}
Generate an edit object from a JS template function

This is the recommended way as it gives you a crazy level of flexibility :D

It's basically the same as the above JS file approach, but instead of returning an object, the JS file exports a function. All additional command line arguments will be passed to that function.

For instance, to add different P1449 and P1106 values to different entities, you could write a JS file like this:

// add_P1449_and_P1106.js
module.exports = function (id, someString, quantity) {
  return {
    id: id,
    claims: {
      P1449: someString,
      P1106: parseInt(quantity)
    }
  }
}

that can then be called as follow:

wb edit-entity ./add_P1449_and_P1106.js Q1 abc 123
wb edit-entity ./add_P1449_and_P1106.js Q2 def 456
wb edit-entity ./add_P1449_and_P1106.js Q3 ghi 789

This way, you can generate infinitely flexible templates. See wikibase-cli edit template collection for some examples.

A good way to start writting a template function starting from an existing entity is to use the generate-template command:

# When generating templates for only one entity, JS is the default format,
# and comes with helpful labels as comments, to make ids less obscure
wd generate-template Q4115189 > Q4115189.edit-template.js
# Do your modifications, and then
wd edit-entity ./Q4115189.edit-template.js

# Note that it can also be used to create entities
wd generate-template Q4115189 --create-mode > Q4115189.create-template.js
wd create-entity ./Q4115189.create-template.js
# Note that this id- and guid-less template can be turned back into an addition-only edit template
# by setting an `id` in the returned object
wd edit-entity ./Q4115189.create-template.js Q123

JS templates are very powerful, but can be hard to get started with when you are not very familiar with JS: feel welcome to ask for help to get started!

Some examples of how such a dynamic template can be useful:

transform input
const doSomeComplexTransformation = function (quantity) {
  return parseInt(quantity) * 2
}

module.exports = function (id, quantity) {
  return {
    id: id,
    claims: {
      P1106: doSomeComplexTransformation(quantity)
    }
  }
}

Demo: See how this principle was applied to create many items from a single JS template file: Create missing HTTP Status Codes items on Wikidata

fetch additional data

The exported function can be an async function, so you could fetch data during the transformation process:

const fetchSomeData = require('./fetch_some_data.js')
const doSomeComplexTransformation = async function (quantity) {
  return quantity * 2
}

module.exports = async function (id, someExternalId) {
  const initialQuantity = await fetchSomeData(someExternalId)
  const finalQuantity = await doSomeComplexTransformation(initialQuantity)
  return {
    id,
    claims: {
      P1106: finalQuantity
    }
  }
}
generate several edit objects

It can sometimes be convenient to be able to generate several edits from one template call. For that purpose, you can return an array of edit objects. Example hereafter to generate bidirectional relations:

// Add statements that itemA and itemB are different from (P1889) one another
module.exports = function (itemA, itemB) {
  return [
    { id: itemA, claims: { P1889: itemB } },
    { id: itemB, claims: { P1889: itemA } },
  ]
}
inspect generated edit object data

To inspect the data generated dynamically, you can use the --dry option

wb ee ./template.js Q1 abc 123 --dry
template help menu

If you end up using a template often, it can be useful to be able to easily remember how to use it; this can be done by setting metadata in the template to allow the generation of a help menu: see example

wd ee ./test/assets/edit_data_function.js --help

wb merge-entity

Merge an entity into another (See wd:Help:Merge)

# Merge an item (Q1) into another (Q2)
wb merge-entity Q1 Q2
# Alias:
wb me <from-id> <to-id>

Options:

  • --keep-oldest: Merge the newest entity in the oldest one. By default, the arguments' order determines which entity is kept: the first entity is merged into the second entity.

wb delete-entity

Delete an entity (See mw:Page deletion)

# Delete an item
wb delete-entity Q1
# Delete a property
wb delete-entity P1
# Alias:
wb de <entity-id>

edit summary

It's good practice to fill in the Edit Summary field, as it helps everyone to understand what is changed, such as when perusing the history of the page. [source]

For any of the edit commands, you can add an edit summary with -s, --summary:

wb add-alias Q4115189 fr "lorem ipsum" --summary 'this HAD to be changed!'

The summary can also be set from an edit object:

wb create-entity '{"labels":{"la":"lorem ipsum"},"summary":"creating some fantastic item here"}'

baserevid

baserevid: An id for the last known revision that must be passed so that the server can detect edit collisions. [source]

For any of the edit commands, you can pass a base revision id with --baserevid:

# This command will fail with a "cant-load-entity-content" error, as 1 isn't the current lastrevid
wb add-alias Q4115189 fr "lorem ipsum" --baserevid 1

Alternatively, the baserevid can be set within an edit object:

wb edit-entity '{"id":"Q4115189","labels":{"la":"lorem ipsum"},"baserevid":1234}'

There are 2 ways to get the current revision id:

  • request it directly
baserevid=$(wb data Q4115189 --props info | jq '.lastrevid')
wb add-alias Q4115189 fr "ipsum lorem" --baserevid "$baserevid"
  • get the id after an edit
baserevid=$(wb add-alias Q4115189 fr "lorem ipsum" | jq '.entity.lastrevid')
wb add-alias Q4115189 fr "ipsum lorem" --baserevid "$baserevid"

batch mode

All write operations commands accept a -b, --batch option. In batch mode, arguments are provided on the command standard input (stdin), with one operation per line. If the edited Wikibase instance is Wikidata, batch edits will automatically be grouped within an Edit groups; you are thus encouraged to set a summary (with the -s, --summary option) as it will be used as label for the edit group (example).

So instead of:

wb add-claim Q1 P123 123
wb add-claim Q2 P124 'multiple words value'
wb add-claim Q3 P125 '{ "time": "1800", "precision": 7 }'

wb create-entity '{"labels":{"en":"foo"}}'
wb create-entity '{"labels":{"en":"bar"}}'
wb create-entity '{"labels":{"en":"buzz"}}'

wb edit-entity ./template.js Q1 abc 123
wb edit-entity ./template.js Q2 def 456
wb edit-entity ./template.js Q3 ghi 789

you can write:

# NB: simple arguments without spaces (such as in the 1st case hereafter)
# don't need to be wrapped in a JSON array, but it is required for arguments
# that would be harder/error-prone to parse otherwise (2nd and 3rd cases hereafter)
echo '
Q1 P123 123
[ "Q2", "P124", "multiple words value" ]
[ "Q3", "P125", { "time": "1800", "precision": 7 } ]
' | wb add-claim --batch

echo '
{"labels":{"en":"foo"}}
{"labels":{"en":"bar"}}
{"labels":{"en":"buzz"}}
' | wb create-entity --batch

echo '
./template.js Q1 abc 123
./template.js Q2 def 456
./template.js Q3 ghi 789
' | wb edit-entity --batch

# In that last case, the first argument being always the same,
# it could also be written like this:
echo '
Q1 abc 123
Q2 def 456
Q3 ghi 789
' | wb edit-entity ./template.js --batch

Or more probably passing those arguments from a file:

cat ./add_claim_newline_separated_command_args | wb add-claim --batch
cat ./create_entity_newline_separated_command_args | wb create-entity --batch
cat ./edit_entity_newline_separated_command_args | wb edit-entity --batch

# Which can also be written
wb add-claim --batch < ./add_claim_newline_separated_command_args
wb create-entity --batch < ./create_entity_newline_separated_command_args
wb edit-entity --batch < ./edit_entity_newline_separated_command_args

# Or using the short command and option names
wb ac -b < ./add_claim_newline_separated_command_args
wb ce -b < ./create_entity_newline_separated_command_args
wb ee -b < ./edit_entity_newline_separated_command_args

Request parameters in batch mode

To pass parameters such as summary or baserevid, the JSON syntax is the recommended syntax:

echo '
{ "id": "Q1", "labels": { "en": "foo" }, "summary": "lorem ipsum", "baserevid": 123 }
{ "id": "Q2", "labels": { "en": "bar" }, "summary": "lorem ipsum", "baserevid": 456 }
{ "id": "Q3", "labels": { "en": "buzz" }, "summary": "lorem ipsum", "baserevid": 789 }
' | wb edit-entity --batch

Batch process logs

The command output (stdout) will be made of one Wikibase API response per line, while stderr will be used for both progression logs and error messages. For long lists of commands, you could write those outputs to files to keep track of what was done, and, if need be, where the process exited if an error happened. This can be done this way:

# Redirect stdout and stderr to files
wb ac -b < ./args_list > ./args_list.log 2> ./args_list.err
# In another terminal, start a `tail` process at any time to see the progression. This process can be interrupted without stoppping the batch process
tail -f ./args_list.log ./args_list.err

Handle batch errors

If one of the batch operation encounters an error, the default behavior is to stop the batch there, the last line logged on stdout being the line that triggered the error, the error itself being logged on stderr.

In case you would prefer to continue to process the batch rather than exiting, you can set the --no-exit-on-error option:

wb add-claim --batch --no-exit-on-error < ./args_list > ./args_list.log 2> ./args_list.err

This can come handy for long batches, where you might encounter errors such as edit conflicts.

Options

Options common to all edit operations

maxlag

Set the maxlag value (see also config#maxlag)

The default value is 5, meaning that you will tell the server that you accept to wait if the server has a lag of 5 seconds or more.

If you are not in a hurry, you can set an even nicer value, like 2

wb add-claim Q4115189 P1106 123 --maxlag 2

If you want that command to be done already, you can go for a more aggressive value and be done with it :warning: should be avoided when you have a long command queue, typically in --batch mode

wb add-claim Q4115189 P1106 123 --maxlag 100

Demos