Referential Functions

Working with references in karma.run is quite common.

referred

available since: 1.0.0

Returns a list of refs to the graph referees (objects pointed to by) argument "from", in model "in".

struct {from :ref?
in :refmodel(M)
} → listrefM

Example:

Query:

e.referred({from: e.refTo(e.first(e.all(e.tag(d.string("_user"))))), 
in: e.tag(d.string("_role")), 
})

Result:

[
  [
    "IJLixqQoLqMhmYTv",
    "NCiMYqVtNHvULnNa"
  ]
]

Notes:

This example yields a list of objects in model _role that have an incoming reference from the first object in model _user.

relocateRef

available since: 1.0.0

Takes an arbitrary ref and a model ref. Returns the corresponding ref in the target model.

struct {model :refmodel(M)
ref :ref?
} → refM

resolveAllRefs

available since: 1.0.0

resolveAllRefs replaces all refs in its argument with the value they reference and returns the mapped structure.

T → T

Example:

Query:

e.resolveAllRefs(e.resolveAllRefs(e.first(e.all(e.tag(d.string("_user"))))))

Result:

{
  "password": "",
  "roles": [
    {
      "name": "admins",
      "permissions": {
        "create": {
          "function": [
            [
              "_"
            ],
            [
              {
                "data": {
                  "bool": true
                }
              }
            ]
          ]
        },
        "delete": {
          "function": [
            [
              "_"
            ],
            [
              {
                "data": {
                  "bool": true
                }
              }
            ]
          ]
        },
        "read": {
          "function": [
            [
              "_"
            ],
            [
              {
                "data": {
                  "bool": true
                }
              }
            ]
          ]
        },
        "update": {
          "function": [
            [
              "_"
            ],
            [
              {
                "data": {
                  "bool": true
                }
              }
            ]
          ]
        }
      }
    }
  ],
  "username": "admin"
}

Notes:

This example yields an object containing _user, _role and _permission expression information, effectively 'joining' all three models into one object.

raphFlow traveses the relationship graph and returns up to 1000 nodes according to a flow parameter. The flow parameter indicates which transitions a breadth-first search is allowed to make from node to node, based on the model of the nodes. The traversal is started at a single node (a persistent object) and moves outward 'in circles'. In the following example, we're executing a graph-traversal starting at the object with ID abcdefghijklmnop in the model with tag myModel. The flow parameter describes the transitions allowed in the search. The first flow argument says that the search is allowed to cross outgoing edges from objects in myModel to modelA and modelD and also include incoming references to myModel from modelB. Analogously, the second flow parameter allows a transition from nodes in modelA through outgoing references to modelC. Similarly, the third flow parameter allows for transitions from objects in modelB to objects in modelD that referencet them.

struct {flow :liststruct {backward :refmodel(Any)
forward :refmodel(Any)
from :refmodel(Any)
}
start :refT
} → mapany

Example:

Query:

e.graphFlow({start: e.refTo(e.first(e.all(e.tag(d.string("_role"))))), 
flow: e.0({from: e.tag(d.string("_role")), 
backward: e.0(e.tag(d.string("_user"))), 
forward: e.0(e.tag(d.string("_expression"))), 
}), 
})

Result:

{
  "IJLixqQoLqMhmYTv": {
    "NCiMYqVtNHvULnNa": {
      "name": "admins",
      "permissions": {
        "create": [
          "jHLdjHOYpBUwPpqu",
          "NMpYxmLpKpVNPoaX"
        ],
        "delete": [
          "jHLdjHOYpBUwPpqu",
          "NMpYxmLpKpVNPoaX"
        ],
        "read": [
          "jHLdjHOYpBUwPpqu",
          "NMpYxmLpKpVNPoaX"
        ],
        "update": [
          "jHLdjHOYpBUwPpqu",
          "NMpYxmLpKpVNPoaX"
        ]
      }
    }
  },
  "jHLdjHOYpBUwPpqu": {
    "NMpYxmLpKpVNPoaX": {
      "function": [
        [
          "_"
        ],
        [
          {
            "data": {
              "bool": true
            }
          }
        ]
      ]
    }
  },
  "wZpFlUFuWdlcpxRs": {
    "AYhiHRlKlabYansY": {
      "password": "",
      "roles": [
        [
          "IJLixqQoLqMhmYTv",
          "NCiMYqVtNHvULnNa"
        ]
      ],
      "username": "admin"
    }
  }
}

Notes:

yields a struct with keys corresponding to the IDs of _role, _user and _expression. Each field contains a (potentially empty) map from IDs to objects in those models. The result set always includes the start node.

resolveRefs

available since: 1.0.0

ResolveRefs performs a 'search and replace' operation in any given value. It looks for outgoing references of a list of models and replaces those references with the actual referenced objects.

struct {models :listrefmodel(S)
value :T
} → T

Example:

Query:

e.resolveRefs(e.resolveRefs(e.first(e.all(e.tag(d.string("_user")))), e.0(e.tag(d.string("_role")))), e.0(e.tag(d.string("_expression"))))

Result:

{
  "password": "",
  "roles": [
    {
      "name": "admins",
      "permissions": {
        "create": {
          "function": [
            [
              "_"
            ],
            [
              {
                "data": {
                  "bool": true
                }
              }
            ]
          ]
        },
        "delete": {
          "function": [
            [
              "_"
            ],
            [
              {
                "data": {
                  "bool": true
                }
              }
            ]
          ]
        },
        "read": {
          "function": [
            [
              "_"
            ],
            [
              {
                "data": {
                  "bool": true
                }
              }
            ]
          ]
        },
        "update": {
          "function": [
            [
              "_"
            ],
            [
              {
                "data": {
                  "bool": true
                }
              }
            ]
          ]
        }
      }
    }
  ],
  "username": "admin"
}

Notes:

This example yields an object containing _user and _role information, effectively "joining" the two models into one object.

referrers

available since: 1.0.0

Returns a list of refs to the graph referrers (objects with refs to) argument "of", in model "in".

struct {in :refmodel(M)
of :ref?
} → listrefM

Example:

Query:

e.referrers({of: e.refTo(e.first(e.all(e.tag(d.string("_role"))))), 
in: e.tag(d.string("_user")), 
})

Result:

[
  [
    "wZpFlUFuWdlcpxRs",
    "AYhiHRlKlabYansY"
  ]
]

Notes:

This example yields a list of objects in model _user that have an outgoing reference to the first object in model _role.

resolveRef

available since: 1.0.0

Takes a value and replaces references to models listed in argument "models" with their pointed-to values.

struct {models :listrefmodel(M)
value :T
} → T

model

available since: 1.0.0

Model takes a string and returns a ref to the model with the id in the string.

string → refmodel(M)

Example:

Query:

e.refTo(e.first(e.all(e.tag(d.string("_tag")))))

Result:

[
  "BhngXKDJZDJdExxN",
  "FdWoWlAzKlvClYTW"
]

Notes:

yields an opaque ref value to the first _tag object

tag

available since: 1.0.0

Resolves a tag string to its model reference. Returns an error if the tag is not defined.

string → refmodel(M)

Example:

Query:

e.tag(e.data(d.string("_tag")))

Result:

[
  "fjxRgZyTyjEMruRg",
  "BhngXKDJZDJdExxN"
]

Notes:

yields a reference to the _user model

tagExists

available since: 1.0.0

tagExists reports whether a given tag string is defined.

string → bool

Example:

Query:

e.data(d.tuple(d.expr(e.tagExists(d.string("_user"))), d.expr(e.tagExists(d.string("idonotexist")))))

Result:

[
  true,
  false
]

refTo

available since: 1.0.0

Takes a persistent value and returns a ref to it

T → refT

Example:

Query:

e.refTo(e.first(e.all(e.tag(d.string("_tag")))))

Result:

[
  "BhngXKDJZDJdExxN",
  "FdWoWlAzKlvClYTW"
]

Notes:

yields an opaque ref value to the first _tag object

allReferrers

available since: 1.0.0

allReferrers takes a single argument, which is any ref value and returns a list of ref-values. The list contains refs to all objects in the graph that have at least one reference to the argument.

ref? → listref?

Example:

Query:

e.createMultiple(e.tag(d.string("_model")), {modelA: f.function(["_refs_0"], e.data(m.string())), 
modelB: f.function(["_refs_1"], e.data(m.ref())), 
modelC: f.function(["_refs_2"], e.data(m.ref())), 
})

Result:

{
  "modelA": [
    "fjxRgZyTyjEMruRg",
    "CpFUfymRfLqHokaT"
  ],
  "modelB": [
    "fjxRgZyTyjEMruRg",
    "dCMhzSbSEFuIukOK"
  ],
  "modelC": [
    "fjxRgZyTyjEMruRg",
    "GaTFOaGRpQBpoicX"
  ]
}

Example:

Query:

e.allReferrers({scope: "record", 
})

Result:

[
  [
    "GaTFOaGRpQBpoicX",
    "ybRLGuhGhyEjgZCU"
  ],
  [
    "dCMhzSbSEFuIukOK",
    "OTlVTeZCZRbUshJQ"
  ]
]

ref

available since: 1.0.0

Ref takes a struct with two fields: model and id. Field model must hold a ref to a model. Field id is a string. It returns a reference to the object with the argument ID in the argument model.

struct {id :string
model :string
} → refT

Example:

Query:

e.data(d.ref("BhngXKDJZDJdExxN", "FdWoWlAzKlvClYTW"))

Result:

[
  "BhngXKDJZDJdExxN",
  "FdWoWlAzKlvClYTW"
]