DB module documentation

A resource is a node in a semantic graph.

Converts an absolute URI to a resource

Converts an absolute URI to a resource or returns Nothing if there is no such resource.

Converts a relative URI to a resource starting from the given resource

Things that are addressed by URI and browsed as a tree of named children. Both Resource and Variable are browsable: a resource is browsed through the resources it consists of, a variable through its own child structure.

Returns a child Browsable of the specified parent that has that is the child of the specified parent with the specified name path.

Like childWithPath but returns Maybe a which will be Nothing if no child was found.

subject # predicate returns all objects with the given subject and predicate.

Assumes that there is exactly one object with the given subject and predicate and returns it.

If there is exactly one object with the given subject and predicate, possibleObject subject predicate returns it. Otherwise, it returns Nothing.

possibleObjectWithType subject predicate type returns the single object with the given subject and predicate that is an instance of type, or Nothing if there is no such object or more than one.

objectsWithType subject predicate type returns those objects with the given subject and predicate that are instances of type. Duplicates are removed and the order of the result is unspecified.

assertedObjects subject predicate` returns all asserted objects defined in the specified subjects with the given predicate.

A statement is an edge in a semantic graph.

Returns the subject of the statement, the resource the edge starts from.

Returns the predicate of the statement, the relation the edge stands for.

Returns the object of the statement, the resource the edge points to.

statements subject predicate` returns all statements with the given subject and predicate.

Assumes that there is exactly one statement with the given subject and predicate and returns it.

assertedStatements subject predicate` returns all asserted statements defined in the specified subjects with the given predicate.

isAsserted statement subject tells whether the statement was inherited by subject from an assertion made by one of its types instead of being stated on subject itself. It compares subject with the subject recorded in the statement, so it is meaningful only for a statement that was read using subject as the query subject.

singleTypeOf resource baseType returns the principal type of resource that is baseType or inherits from it. Fails if there is not exactly one such type.

As singleTypeOf but returns Nothing when the resource has no principal type inheriting from the given base type, or more than one.

Returns the inverse relation of the given relation. Fails if the relation has no inverse.

As inverseOf but returns Nothing when the relation has no inverse or more than one.

Returns all types the given type inherits from, transitively. The type itself is not included in the result.

Returns all relations the given relation is a subrelation of, transitively. The relation itself is not included in the result.

Reads the value of a literal that is an object with the given subject and predicate

Reads the value of the literal that is an object with the given subject and predicate, or Nothing if there is no such object, if there is more than one, or if the object holds no value.

Reads the value related to the given subject with the given predicate using the general value mechanism: the object may be a literal, an external value, or a resource that computes its value with the converter declared for it. Fails if there is not exactly one such object or if no value can be produced for it.

Reads the value stored in the given literal as a Dynamic, using the binding implied by the data type recorded in the database. Fails if the resource holds no value. possibleFromDynamic converts the result to a known type.

As relatedValue but the binding comes from the data type recorded in the database instead of from the expected type. The result is not checked against the type the caller expects.

As untypedRelatedValue but returns Nothing when there is no object with the given subject and predicate, when there is more than one, or when the object holds no value.

isInstanceOf r t returns true, if r is an instance of t

isSubrelationOf r s returns true, if r is s or a subrelation of s, directly or transitively

isInheritedFrom r t returns true, if r is t or inherits from t, directly or transitively

isParent a b returns True if a is b or contains b, directly or transitively.

existsStatement subject predicate returns True if there is at least one statement with the given subject whose predicate is the given predicate or one of its subrelations.

existsStatement3 subject predicate object returns True if that statement exists, assertions included.

Returns the predicates of all statements that have the given resource as subject, assertions included.

possiblePredicateByName resource name returns the property relation named name in the domain of one of the principal types of resource, or Nothing if no type of the resource defines a property with that name.

possiblePredicateByNameFromType type name returns the property relation named name in the domain of type or of one of its supertypes, or Nothing if there is no such property.

isAsserted statement subject tells whether the statement was inherited by subject from an assertion made by one of its types instead of being stated on subject itself. It compares subject with the subject recorded in the statement, so it is meaningful only for a statement that was read using subject as the query subject.

Gives the current active model.

Returns the project resource of the current session. Fails if there is no session or no current project.

Returns the root library of the database, the resource at the root of the URI hierarchy.

Returns the ontologies found under the root library.

Gives the current active model if it exists or Nothing otherwise.

Returns the 64-bit unique identifier of the resource.

Returns the resource with the given 64-bit identifier, the inverse of resourceId. Fails if the identifier does not refer to a resource.

Makes a new read request with given procedure for calculating the result. The request is cached only if the current request is listened.

Performs synchronously a new AsyncRead request.

Makes a new read request with given procedure for calculating the result. The request is always cached.

Makes a new read asynchronous request with function to handle the request result. The last isDisposed function parameter is used to determine if the listener is still alive or not.

Performs asynchronously a new Read request with given result and exception handlers.

unaryQuery f x evaluates f x as a separate read request so that the result can be reused. The request is cached only if the current request is listened.

As unaryQuery but the request is always cached.

Creates a new resource.

Adds a statement to the semantic graph.

claimWithInverse subject predicate inverse object adds the statement (subject, predicate, object) and, when inverse is Just i, also the statement (object, i, subject). Nothing checks that i really is the inverse of predicate, that is the caller's responsibility. Needs a write transaction.

Removes a statement with the given subject, predicate and object

denyByPredicate subject predicate removes every statement that has the given subject and the given predicate or any of its subrelations, together with the inverses of those statements. Needs a write transaction.

Removes every statement that has the given resource as subject, together with the inverses of those statements. Needs a write transaction.

claimAssertion type predicate object adds an assertion to type so that every instance of type gets the statement (instance, predicate, object) without it being stated on the instance itself. Needs a write transaction.

Sets the value of the literal that is an object with the given subject and predicate.

claimRelatedValueWithType subject predicate type value sets the value of the literal that is the object of subject with predicate and gives the literal the type type. Needs a write transaction.

As claimRelatedValue but the binding is chosen from the runtime class of the value instead of from the expected type. Needs a write transaction.

Removes the literal value of the given resource, if it has one. Needs a write transaction.

addToOrderedSet s e adds element e to ordered set s

addFirstToOrderedSet s e adds element e to ordered set s as the first element

addAfterToOrderedSet s p e adds element e to ordered set s after element p

addBeforeToOrderedSet s p e adds element e to ordered set s before element p

removeFromOrderedSet s e removes element e from ordered set s

setOrderedSet s [e] makes ordered set s contain exactly the elements [e] in that order, adding and removing links as needed. Returns True if the set changed.

elementsOfOrderedSet s returns the elements of ordered set s in order

Returns the ordered set the given element belongs to. Fails if the element belongs to no ordered set or to more than one.

elementsOfList l returns elements of list l

createList [e] creates a new list containing elements [e]

createListWithType t [e] creates a new list with type t containing elements [e]

insertListBack l [e] inserts elements [e] back to the list l

insertListFront l [e] inserts elements [e] front of the list l

removeListElement l e removes a element e from the list l

swapListElementWithPrevious l e exchanges element e with the element before it in list l. Returns False and changes nothing if e is not in the list or is already its first element.

swapListElementWithNext l e exchanges element e with the element after it in list l. Returns False and changes nothing if e is not in the list or is already its last element.

Executes a read transaction and waits that it completes.

Begins a read transaction and immediately returns.

Executes a write transaction and waits that it completes.

Executes a delayed write transaction and waits that it completes.

Begins a write transaction and immediately returns.

virtualSyncWriteMem id f executes f as a write into the memory-persistent virtual graph with the given identifier and waits that it completes. The virtual graph is created if it does not exist yet, and its contents are lost when the session ends. Needs a write transaction.

As virtualSyncWriteMem but writes into the workspace-persistent virtual graph with the given identifier. Such a graph is stored on disk and restored when the workspace is opened again.

Turns a one-argument function that needs a read transaction into one that can be called without a transaction, by executing it in a read transaction of its own and waiting that it completes.

As lift1Read but for a function of two arguments.

As lift1Read but for a function of three arguments.

Turns a one-argument function that needs a write transaction into one that can be called without a transaction, by executing it in a write transaction of its own and waiting that it completes.

As lift1Write but for a function of two arguments.

As lift1Write but for a function of three arguments.

Attaches a comment to the ongoing write transaction. The comment is stored in the metadata of the change set and is what the undo history shows for the operation. Needs a write transaction.

Sets the GRAPH_HINT_SYNCHRONOUS hint of the current graph handle. Use withGraphHintBoolean to set the hint for the duration of one function only.

Turns maintenance of the dependency index back on for the ongoing write transaction. Needs a write transaction.

Stops maintaining the dependency index for the ongoing write transaction. The setting is reset when the transaction ends. Needs a write transaction.

Marks the beginning of the ongoing write transaction as an undo point. Needs a write transaction. Calling it more than once during the same transaction has no further effect. startUndoPoint also attaches a comment that the undo history can show.

Marks the beginning of the ongoing write transaction as an undo point and attaches the given comment to it, which is what the undo history shows for the operation. Needs a write transaction.

Undoes the last write operation and returns a description of what was reverted. If the undo history is empty, nothing is changed and the description says so.

Redoes the last undone write operation and returns a description of what was redone. If the redo history is empty, nothing is changed and the description says so.

As undo but undoes the given number of operations.

findFreshName proposition container returns proposition if no child of container has that name, and otherwise proposition followed by a space and a running number that makes it unique.

As findFreshName but separates the running number from the name with an underscore instead of a space.

Escapes a string so that it can be used as one segment of a URI, replacing the characters that are not allowed there, the path separator included, with %NN escapes.

Turns the %NN escapes of a URI segment back into the characters they stand for.

Splits an absolute URI at its last path separator and returns the namespace and the local name as a two element list. Fails if the URI has no path separator.

Creates a new resource, applies each of the given specifications to it and returns it. The specifications are functions such as hasName, hasType, hasParent and hasProperty. Needs a write transaction.

Creates a new cluster set identified by the given resource. Clusters are the units in which the database stores resources. Fails if a cluster set with that identifier already exists. Needs a write transaction.

Chooses the cluster set that resources created later in this transaction go into, based on the cluster set of the given resource. Falls back to the cluster set of the root library if the resource does not determine one. Needs a write transaction.

sortByCluster xs f orders the elements of xs by the cluster of the resource that f gives for each of them.

Runs the given command through the database debug support and returns its output. The command is passed on as exec command.

As queryDebugSupport but the command is passed on as list command.

dryRun

If dryRun is True, migrations will not perform any database changes during their execution but can report what changes would be made. When false, changes will be done immediately by the migration.

collectDetailedReportData

Defines whether the migration should collect data for performed and failed migrations in the collections included in this class. If the client only wants to know whether migration succeeded or failed somehow, this can be set to false by the constructor.

collectApplicableChanges

If dryRun is True and collectApplicableChanges is True the migration will collect the statement changes that would be made into the returned MigrationReport. The changes can then be applied later with applyMigrationChanges. If dryRun is False this option has no effect.

The result of a domain migration: what was processed, what was migrated and what failed. Read it as text with dumpMigrationReport or dumpMigrationReport2, and apply the changes a dry run collected with applyMigrationChanges. How much detail the report holds is decided by the MigrationConfig the migration was run with.

migrateDomainWithSpecs config migratedResource migrationSpecifications

Executes graph domain based migration for the specified migratedResource based on the provided migration specifications.

The function produces a MigrationReport that can be dumped to text or used to apply the pre-computed migration steps after resolving the migration with a dry-run.

Migration specifications are provided as a list of (sourceNamespace, [targetNamespace]) specifications. A single migration specification consists of:

• a single source namespace (such as a shared library version)
• one or more target namespaces (such as a new version of the same shared library)

Multiple specifications can be provided to the function.

The migration will process all database statements of the computed graph domain for migrationResource and attempt to migrate any statement predicate and object resources that are not internal to the computed graph domain. If the encountered resources reference a resource in any of the provided source namespaces, the system will try to look for a matching resource in any of the target namespaces provided for the matched source namespace.

If a match is found in a target namespace, the statement containing the migrated resources will first be denied and then reclaimed using the migrated predicate and/or object.

If no match can be found in any of the provided target namespaces, migration for that specific resource is considered failed and will be included in the produced MigrationReport according to what is specified in the provided MigrationConfig.

migrateDomain config migratedResource sourceContainer targetContainer

Equal to migrateDomainWithSpecs config migratedResource [(sourceContainer, [targetContainer])].

If MigrationConfig collectApplicableChanges was set to True and MigrationConfig dryRun set to True, this function can be used to apply the collected migration operations in one go after first resolving them with migrateDomainWithSpecs or migrateDomain.

Formats a migration report as text: a summary followed by one section for each kind of change, listing the subjects whose statements, predicates or objects were changed and the ones whose migration failed.

Formats a migration report as text like dumpMigrationReport but lists the changes grouped by subject, marking the changed predicates and objects with an asterisk. The detailed part is present only if the migration was run with collectDetailedReportData set to True.

The key of the graph hint that controls synchronous reading. While the hint is True, a read of external data that would otherwise yield a cached pending placeholder waits until the real value has been computed. Set it with withGraphHintBoolean or makeSynchronous.

Runs the triggers attached to the given resource once and then deactivates them.

Registers a listener that is called after every completed write transaction of the current session.

Returns all asserted objects with the given subject and predicate as a Java collection. assertedObjects is the same query with the result converted to a list.

Returns all asserted statements with the given subject and predicate as a Java collection. assertedStatements is the same query with the result converted to a list.

claimRelatedValueWithType_ subject predicate type value binding sets the value of the literal that is the object of subject with predicate, gives the literal the type type and serializes the value with the given binding. Needs a write transaction.

claimRelatedValue_ subject predicate value binding sets the value of the literal that is the object of subject with predicate, serializing it with the given binding. Any previous value is replaced and the literal is created if it does not exist yet. Needs a write transaction. claimRelatedValue is the same function with the binding taken from the type of the value.

Copies the elements of a Java collection into a list.

copyTo targetContainer source copies source into targetContainer and returns the copy. How the copy is attached to the container is decided by the paste handler adapted from the container. Fails if the copy produced no resource. Needs a write transaction.

denyRelatedValue subject predicate removes every statement with the given subject and predicate together with the literals those statements point to. Needs a write transaction.

Deletes the contents of the trash bin of the current project and then purges the database. The deletion cannot be undone.

Ends writing into the current cluster and starts a new one, so that resources created after this call go into the new cluster. Needs a write transaction.

Returns the data type of the value stored in the given literal. Fails if the resource has no data type.

Returns True if the given resource is immutable. Immutability is a property of the cluster the resource belongs to.

Returns True if the resource is stored in the persistent database and False if it exists only in a virtual graph.

Returns all objects with the given subject and predicate as a Java collection. subject # predicate is the same query with the result converted to a list.

Tries to convert the given Dynamic value to a value with the inferred type

Reads the value of the literal that is an object with the given subject and predicate as an integer, or Nothing if there is no such value.

Reads the value of the literal that is an object with the given subject and predicate as a string, or Nothing if there is no such value.

As relatedValue2 but returns Nothing instead of failing when there is no single object or no value can be produced for it.

As relatedValue_ but returns Nothing when there is no object with the given subject and predicate, when there is more than one, or when the object holds no value.

possibleResourceChild resource name returns the child of resource that has the given name, or Nothing if it has no such child. Only named children are considered, that is, the resources resource consists of that carry a name property.

If there is exactly one statement with the given subject and predicate, possibleStatement subject predicate returns it. Otherwise, it returns Nothing.

prettyPrintResource resource ignoreIdentifiers exports the given resource and everything it contains as a transferable graph and returns it in readable text form. When ignoreIdentifiers is True, the identifier properties of the exported resources are left out of the output.

Simple change / metadata debugging report.

Asks the server to purge the database. If the system property db.purge.discardVirtualGraphs is set to true, all virtual graphs are discarded first.

Reads the value of the single literal that is the object of the given subject and predicate, deserializing it with the given binding. Fails if there is not exactly one such object or if the object holds no value. relatedValue is the same function with the binding taken from the expected type.

Reads the value of the single literal that is the object of the given subject and predicate and returns it as a Variant, a value packaged together with its data type. Fails if there is not exactly one such object or if the object holds no value.

As relatedValue2 but returns the value as a Variant, that is, packaged together with its data type.

Removes a listener registered with addMetadataListener.

Returns the resources the given resource consists of.

Reinterprets a value as a Java collection without converting or checking anything. The result is usable only if the value already is a Java collection.

Executes the given function and returns its result. If the function throws, the exception is logged and null is returned in its place, so the failure only shows up where the result is used.

Turns maintenance of the dependency index off or on for the ongoing write transaction. The setting is reset when the transaction ends. Needs a write transaction.

Returns all statements with the given subject and predicate as a Java collection. statements is the same query with the result converted to a list.

As activateOnce but runs the triggers inside the ongoing write transaction. Needs a write transaction.

Stores the given value into the given resource as its literal value, replacing any previous value. Needs a write transaction.

As untypedValueOf but returns Nothing when the resource holds no value.

Applies each of the given specifications to an existing resource and returns the resource. See newEntity. Needs a write transaction.

withGraphHintBoolean key value f executes f with the given boolean graph hint in effect and restores the previous hints afterwards, also when f fails. See GRAPH_HINT_SYNCHRONOUS.