Options
All
  • Public
  • Public/Protected
  • All
Menu

A pattern to update the properties of matching subjects in the domain.

Examples:


Delete a subject property

{
  "@delete": {
    "@id": "fred",
    "name": "Fred"
  }
}

Delete a property, where another property has a value

{
  "@delete": {
    "@id": "?id",
    "age": "?any"
  },
  "@where": {
    "@id": "?id",
    "name": "Fred",
    "age": "?any"
  }
}

Update a subject property

{
  "@delete": {
    "@id": "fred",
    "name": "Fred"
  },
  "@insert": {
    "@id": "fred",
    "name": "Fred Flintstone"
  }
}

Replace all of a subject's properties

{
  "@delete": {
    "@id": "fred",
    "?prop": "?value"
  },
  "@insert": {
    "@id": "fred",
    "age": 50,
    "name": "Fred Flintstone"
  }
}
see

json-rql update

Hierarchy

Index

Properties

Optional @agree

@agree: any

If this key is included and the value is truthy, this update is an agreement. Use of an agreement will guarantee that all clones converge on the "agreed" data state (although they may continue to change thereafter). Agreements may cause concurrent operations on other clones to be voided, that is, reversed and removed from history.

The use of an agreement usually requires either that some coordination has occurred in the app (externally to m-ld), or that the local user has the authority to unilaterally agree. The precondition will be automatically checked by an AgreementCondition at all remote clones. A violation may lead to the originating clone being flagged as malware.

The key value may be used to include any JSON-serialisable proof that applicable agreement conditions have been met, such as a key to a ledger entry.

An update with a falsy flag may be automatically upgraded to an agreement by a constraint.

๐Ÿงช Agreements are an experimental feature. Please contact us to discuss your use-case.

see

the white paper

experimental

Optional @context

@context: Context

An optional JSON-LD Context for the query. Use of a query-specific Context is rarely required, as the context is typically the local application, whose needs are specified by the local clone configuration.

Optional @delete

@delete: Subject | Subject[]

Subjects with properties to be deleted from the domain. Variables can be used without a @where clause, to match any existing value.

Optional @insert

@insert: Subject | Subject[]

Subjects with properties to be inserted into the domain. Variables may be used, values for which will be established as follows:

  • If a @where clause exists, then values matched in the @where clause will be used.
  • If there is no @where, but a @delete clause exists, then values matched in the @delete clause will be used.
  • If a variable value is not matched by the @where or @delete clause as above, no insertion happens (i.e. there must exist a complete solution to all variables in the @insert).

Note that in the case that the @insert contains no variables, there is a difference between matching with a @where and @delete. If a @where clause is provided, it must match some existing data for the inserts to happen. However, if no @where clauses is provided, then the insertion will happen even if nothing is matched by the @delete.

For example, assume this data exists:

{ "@id": "fred", "name": "Fred" }

Compare the following update patterns:

{
  "@delete": { "@id": "fred", "height": "?height" },
  "@insert": { "@id": "fred", "height": "6" }
}

The pattern above updates Fred's height to 6, even though no prior height value exists.

{
  "@delete": { "@id": "fred", "height": "?height" },
  "@insert": { "@id": "fred", "height": "6" },
  "@where": { "@id": "fred", "height": "?height" }
}

The pattern above does nothing, because no prior height value is matched by the @where.

Optional @update

@update: Subject | Subject[]

Subjects with properties to be updated in the domain. By default, any subject property included will have its old value deleted and the provided value inserted, for example:

{
  "@update": { "@id": "fred", "height": "6" }
}

is generally equivalent to:

{
  "@delete": { "@id": "fred", "height": "?" },
  "@insert": { "@id": "fred", "height": "6" }
}

All prior values are deleted, so this query form is best suited for 'registers' โ€“ properties that are expected to have a single value. Note that the default behaviour can still lead to multiple values if concurrent updates occur and no constraint exists for the property (a 'conflict').

Variables may be used to match data to update. If the variable appears in the property value position the update will have no effect unless an in-line operation is used, e.g.

{
  "@update": { "@id": "fred", "likes": { "@value": "?old", "@plus": 1 } }
}

Shared data types operating on the data may change the default behaviour to make an @update logically different to a @delete and an @insert, particularly when using an in-line operation.

Optional @where

@where: Subject | Subject[] | Group

The data pattern to match, as a set of subjects or a group. Variables are used as placeholders to capture matching properties and values in the domain.

Examples:


Match a subject by its @id

{
  ...
  "@where": { "@id": "fred" }
}

Match a subject where any property has a given value

{
  ...
  "@where": {
    "@id": "?id",
    "?prop": "Bedrock"
  }
}

Match a subject with a given property, having any value

{
  ...
  "@where": {
    "@id": "?id",
    "name": "?name"
  }
}

The Javascript engine supports filters for subject identities, properties and values, including inline filters.

Legend

  • Constructor
  • Property
  • Method
  • Property
  • Method
  • Inherited property
  • Inherited method
  • Static property
  • Static method
  • Protected method

Generated using TypeDoc. Delivered by Vercel. @m-ld/m-ld - v0.10.0 Source code licensed MIT. Privacy policy