MarkLogic Server 11.0 Product Documentation

Semantic Graph Developer's Guide — Chapter 8

CREATE

This operation creates a graph. If the graph already exists, an error will be returned unless the SILENT option is used. The contents of already existing graphs remain unchanged. If you do not have permission to create the graph, an error is returned (unless the SILENT option is used).

The syntax for a CREATE operation is:

CREATE ( SILENT )? GRAPH IRIref

If the SILENT option is used, the operation will not return an error. The GRAPH IRIref option specifies the IRI for the new graph.

For example:

CREATE GRAPH <http://marklogic.com/semantics/tutorial/update> ;

If the specified destination graph does not exist, the graph will be created. The CREATE operation will create a graph with the permissions specified through sem:sparql-update, or with the user's default permission if no permissions are specified.

DROP

The DROP operation removes the specified graph or graphs from the Graph Store. The syntax for a DROP operation is:

DROP ( SILENT )? GRAPH IRIref | DEFAULT |NAMED | ALL ) 

The GRAPH keyword is used to remove a graph specified by IRIref . The DEFAULT keyword option is used to remove the default graph from the Graph Store. The NAMED keyword is used to remove all named graphs from the Graph Store. All graphs are removed from the Graph Store with the ALL keyword; this is the same as resetting the Graph store.

For example:

DROP SILENT GRAPH <http://marklogic.com/semantics/tutorial/intro> ;

After successful completion of this operation, the specified graphs are no longer available for further graph update operations. This operation returns an error if the specified named graph does not exist. If SILENT is present, the result of the operation will always be success.

If the default graph of the Graph Store is dropped, MarkLogic creates a new, empty default graph with the user's default permissions.

COPY

The COPY operation is used for inserting all of the triples from a source graph into a destination graph. Triples from the source graph are not affected, but triples in the destination graph, if any exist, are removed before the new triples are inserted.

The syntax for a COPY operation is:

COPY ( SILENT )? ( ( GRAPH )? IRIref_from | DEFAULT) TO ( ( GRAPH )? 
    IRIref_to | DEFAULT ) 

The COPY operation copies permissions from a source graph to the destination graph. Since source graph has the permission info, $perm parameter in sem:sparql-update does not apply in a COPY operation.

For example:

COPY <http://marklogic.com/semantics/tutorial/intro> TO
  <http://marklogic.com/semantics/tutorial/start> ;

If the destination graph does not exist, it will be created. The operation returns an error if the source graph does not exist. If the SILENT option is used, the result of the operation will always be success.

The COPY operation is similar to dropping a graph and then inserting a new graph:

DROP SILENT (GRAPH IRIref_to | DEFAULT); INSERT { ( GRAPH IRIref_to )?
    { ?s ?p ?o } } WHERE { ( GRAPH IRIref_from )? { ?s ?p ?o } } 

If COPY is used to copy a graph onto itself, no operation is performed and the data is left as it was.

If you want the update to fail when the destination graph does not already exist, the existing-graph option in sem:sparql-update needs to be specified. If you copy into a new graph, that new graph takes the permissions of the graph that you copied from. If you copy into an existing graph, the permssions of that graph do not change.

MOVE

The MOVE operation is used for moving all triples from a source graph into a destination graph. The syntax for a MOVE operation is:

MOVE (SILENT)? ( ( GRAPH )? IRIref_from | DEFAULT) TO ( ( GRAPH )?
    IRIref_to | DEFAULT) 

The source graph is removed after insertion. Triples in the destination graph, if any exist, are removed before destination triples are inserted.

For example:

MOVE <http://marklogic.com/semantics/tutorial/queries> TO 
  <http://marklogic.com/semantics/tutorialSearches> ;

The graph <http://marklogic.com/semantics/queries> is removed after its triples have been inserted into <http://marklogic.com/semantics/searches>. Any triples in the graph <http://marklogic.com/semantics/searches> are deleted before the other triples are inserted.

If MOVE is used to move a graph onto itself, no operation will be performed and the data will be left as it was.

If the destination graph does not exist, it will be created. The MOVE operation returns an error if the source graph does not exist. If the SILENT option is used, the result of the operation will always be success.

The MOVE operation is similar to :

DROP SILENT (GRAPH IRIref_to | DEFAULT); INSERT { ( GRAPH IRIref_to )?
    { ?s ?p ?o } } WHERE { ( GRAPH IRIref_from )? { ?s ?p ?o } };
    DROP ( GRAPH IRIref_from | DEFAULT) 

The MOVE operation moves permissions from source graph to destination graph. Since source graph has the permission info, the $perm parameter in sem:sparql-update does not apply to the operation.

If you want the update to fail when the destination graph does not already exist, the existing-graph option in sem:sparql-update needs to be specified. If you copy into a new graph, that new graph takes the permissions of the graph that you copied from. If you copy into an existing graph, the permssions of that graph do not change.

ADD

The ADD operation is used for inserting all triples from a source graph into a destination graph. The triples from the source graph are not affected, and existing triples from the destination graph, if any exist, are kept intact.

The syntax for an ADD operation is:

ADD ( SILENT )? ( ( GRAPH )? IRIref_from | DEFAULT) TO ( ( GRAPH )? IRIref_to | DEFAULT) 

For example:

ADD <http://marklogic.com/semantics/tutorial/queries> TO 
  <http://marklogic.com/semantics/searches> ;

If ADD is used to add a graph onto itself, no operation will be performed and the data will be left as it was. If the destination graph does not exist, it will be created. The ADD operation returns an error if the source graph does not exist. If the SILENT option is used, the result of the operation will always be success.

If you are adding triples into a new graph, you can set the permissions of the new graph through sem:sparql-update. If no permissions are specified, your default graph permissions will be applied to the graph.

The ADD operation is equivalent to:

INSERT { ( GRAPH IRIref_to )? { ?s ?p ?o } } WHERE 
    { ( GRAPH IRIref_from )? { ?s ?p ?o } }

If you want the update to fail when the destination graph does not already exist, the existing-graph option in sem:sparql-update needs to be specified. If you copy into a new graph, that new graph takes the permissions of the graph that you copied from. If you copy into an existing graph, the permssions of that graph do not change.

INSERT DATA

INSERT DATA adds triples specified in the request into a graph. The syntax for INSERT DATA is:

INSERT DATA QuadData
(GRAPH VarOrIri) ? {TriplesTemplates}

The QuadData parameter is made up of sets of triple patterns (TriplesTemplates), which can optionally be wrapped in a GRAPH block.

All of the managed triples from a triples document will go into the default graph unless you specify the destination graph when inserting them using SPARQL Update.

If you are inserting triples into a new graph, create the graph with the permissions you want, specified through sem:sparql-update. If you do not specify permissions on the graph, the graph will be created with your default permissions. To manage the permissions of the graph, use sem:graph-add-permissions. See Graph-Level Security for more about permissions and security.

For example, this update uses sem:graph-add-permissions to add update permissions to the sparql-update-role to update for <My Graph>, and inserts three triples into that graph:

xquery version "1.0-ml";
import module namespace sem = "http://marklogic.com/semantics"
  at "/MarkLogic/semantics.xqy";

sem:graph-add-permissions(sem:iri("MyGraph"),
xdmp:permission("sparql-update-role", "update"));
sem:sparql-update('

PREFIX exp: <http://example.org/marklogic/people>
PREFIX pre: <http://example.org/marklogic/predicate>

INSERT DATA {
  GRAPH <MyGraph>{
  exp:John_Smith pre:livesIn "London" .
  exp:Jane_Smith pre:livesIn "London" .
  exp:Jack_Smith pre:livesIn "Glasgow" .
  }}
')

If no graph is described in QuadData, the default graph is assumed (http://marklogic.com/semantics#default-graph). If data is inserted into a graph that does not exist in the Graph Store, a new graph is created for the data with the user's permissions.

This example uses INSERT DATA to insert a triple into a default graph and then insert three triples into a graph named BOOKS.

xquery version "1.0-ml";
import module namespace sem = "http://marklogic.com/semantics"
  at "/MarkLogic/semantics.xqy";

sem:sparql-update('
PREFIX dc: <http://marklogic.com/dc/elements/1.1/>
INSERT DATA
{
  <http://example/book0> dc:title "A default book"
  GRAPH <BOOKS> {<http://example/book1> dc:title "A new book" }
  GRAPH <BOOKS> {<http://example/book2> dc:title "A second book" }
  GRAPH <BOOKS> {<http://example/book3> dc:title "A third book" }
 }
');

This example will delete any book titled A new bookin the graph BOOKS and insert the title Inside MarkLogic Server in its place:

xquery version "1.0-ml";
import module namespace sem = "http://marklogic.com/semantics"
  at "/MarkLogic/semantics.xqy";

sem:sparql-update('
PREFIX dc: <http://marklogic.com/dc/elements/1.1/>
WITH <BOOKS>
DELETE {?b dc:title "A new book"}
INSERT {?b dc:title "Inside MarkLogic Server" }
WHERE {
?b dc:title "A new book".
}')

The WITH keyword means to use this graph (<BOOKS>) in every clause.

DELETE DATA

The DELETE DATA operation removes some triples specified in the request, if the respective graphs in the Graph Store contain them. The syntax for DELETE DATA is:

DELETE DATA QuadData

The QuadData parameter specifies the triples to be removed. If no graph is described in QuadData, then the default graph is assumed.

Any MarkLogic-managed triple that matches subject, predicate, and object on any of the triples specified in QuadData will be deleted. If a graph is specified in QuadData, the scope of deletion is limited to the triples in that graph; otherwise, the scope of deletion is limited to the triples in default graph.

This example deletes triples that match true and Retail/Wholesale from the <http://marklogic.com/semantics/COMPANIES100A/> graph.

PREFIX demov: <http:demo/verb#>
PREFIX demor: <http:demo/resource#>

DELETE DATA
{ 
  GRAPH <http://marklogic.com/semantics/COMPANIES100A/> 
    {
    demor:COMPANY100 demor:listed "true" .
    demor:COMPANY100 demov:industry "Retail/Wholesale" .
  }
}

An error will be thrown if a DELETE DATA operation includes variables or blank nodes. The deletion of non-existing triples has no effect. Any triples specified in QuadData that do not exist in the Graph Store are ignored.

DELETE..INSERT WHERE

The DELETE..INSERT WHERE operation is used to remove and/or add triples from/to the Graph Store based on bindings for a query pattern specified in a WHERE clause. You can use DELETE..INSERT WHERE to specify a pattern to match against and then delete and/or insert triples.

See http://www.w3.org/TR/sparql11-update/#updateLanguage for details.

To delete triples according to a specific pattern, use the DELETE..INSERT WHERE construct without the optional INSERT clause. If you do not specify a graph, you will insert into or delete triples from the default graph (http://marklogic.com/semantics#default-graph), also called the unnamed graph. The syntax for DELETE..INSERT WHERE is:

( WITH IRIref )?
( ( DeleteClause InsertClause? ) | InsertClause )
( USING ( NAMED )? IRIref )*
WHERE GroupGraphPattern
DeleteClause ::= DELETE  QuadPattern 
InsertClause ::= INSERT  QuadPattern 

This operation identifies data using the WHERE clause, which is used to determine matching sequences of bindings for a set of variables. The bindings for each solution are then substituted into the DELETE template to remove triples, and then in the INSERT template to create new triples.

If an operation tries to insert into a graph that does not exist, that graph will be created. DELETE and INSERT run in the same transaction, and obey MarkLogic security rules.

In this example each triple containing Healthcare/Life Sciences will be deleted and two triples and two triples will be inserted, one for Healthcare and a second one for Life Sciences.

PREFIX demov: <http:demo/verb#>

WITH <http://marklogic.com/semantics/COMPANIES100A/>
DELETE
{
  ?company demov:industry "Healthcare/Life Sciences" .
}
INSERT
{ 
  ?company demov:industry "Healthcare" .
  ?company demov:industry "Life Sciences" .
}
WHERE { 
  ?company demov:industry "Healthcare/Life Sciences" .}

Note that the DELETE and INSERT are independent of each other.

DELETE WHERE

The DELETE WHERE operation is used to remove triples from the Graph Store based on bindings for a query pattern specified in a WHERE clause. DELETE WHERE is DELETE..INSERT WHERE with a missing INSERT, which is optional. You can use DELETE WHERE to specify a pattern to match against and then delete the matching triples.

To delete triples according to a specific pattern, use the DELETE WHERE construct without the optional INSERT clause. If you do not specify a graph, you will delete triples from the default graph (http://marklogic.com/semantics#default-graph), also called the unnamed graph.

The syntax for DELETE WHERE is:

( WITH IRIref )?
( ( DeleteClause InsertClause? ) | InsertClause )
( USING ( NAMED )? IRIref )*
WHERE GroupGraphPattern
DeleteClause ::= DELETE  QuadPattern 
InsertClause ::= INSERT  QuadPattern 

This example of DELETE WHERE deletes the sales data for any companies with less than 100 employees from the graph <http://marklogic.com/semantics/COMPANIES100A/>:

PREFIX demov: <http:demo/verb#>
PREFIX vcard: <http:www.w3c.org/2006/vcard/ns#>

WITH <http://marklogic.com/semantics/COMPANIES100A/>
DELETE
{ 
  ?company demov:sales ?sales .
}
WHERE { 
  ?company a vcard:Organization .
  ?company demov:employees ?employees .
}
  FILTER ( ?employees < 100 )

INSERT WHERE

The INSERT WHERE operation is used to add triples to the Graph Store based on bindings for a query pattern specified in a WHERE clause. INSERT WHERE is DELETE..INSERT WHERE with a missing DELETE, which is optional.You can use INSERT WHERE to specify a pattern to match against and then insert triples based on that match.

To insert triples according to a specific pattern, use the INSERT WHERE construct without the optional DELETE clause. If you do not specify a graph, you will insert triples into the default graph (http://marklogic.com/semantics#default-graph), also called the unnamed graph.

The syntax for INSERT WHERE is:

( WITH IRIref )?
( ( DeleteClause InsertClause? ) | InsertClause )
( USING ( NAMED )? IRIref )*
WHERE GroupGraphPattern
DeleteClause ::= DELETE  QuadPattern 
InsertClause ::= INSERT  QuadPattern 

This example of INSERT WHERE finds each company in New York, USA and adds State="NY" and deliveryRegion="East Coast".

PREFIX demov: <http:demo/verb#>
PREFIX vcard: <http:www.w3c.org/2006/vcard/ns#>

WITH <http://marklogic.com/semantics/sb/COMPANIES100A/>
INSERT
{ 
  ?company demov:State "NY" .
  ?company demov:deliveryRegion "East Coast" 
}
WHERE { 
  ?company a vcard:Organization . 
  ?company vcard:hasAddress [ 
    vcard:region "New York" ;
    vcard:country-name "USA"]
}

CLEAR

The CLEAR operation removes all of the triples in the specified graph(s). The syntax for CLEAR is:

CLEAR (SILENT)? (GRAPH IRIref | DEFAULT | NAMED | ALL )

The GRAPH IRIref option is used to remove all triples from the graph specified by GRAPH IRIref. The DEFAULT option is used to remove all the triples from the default graph of the Graph Store. The NAMED option is used to remove all of the triples in all of the named graphs of the Graph Store, and the ALL option is used to remove all triples from all graphs of the Graph Store.

For example:

CLEAR GRAPH <http://marklogic.com/semantics/COMPANIES100A/> ;

This operation removes all of the triples from the graph. The graph and its metadata (such as permissions) will be kept after the graph is cleared. The CLEAR will fail if the specified graph does not exist. If the SILENT option is used, the operation will not return an error.