http://zorba.io/modules/store/dynamic/collections/dml

Description

Before using any of the functions below please remember to import the module namespace:

import module namespace dml = "http://zorba.io/modules/store/dynamic/collections/dml";
This modules provides a set of functions to modify a collection and retrieve the items contained in a particular collection.

Please refer to our documentation for more information about the lifecycle management and the manipulation of such collections.

Module code

Here is the actual XQuery module code.

See also

Authors

Matthias Brantner, David Graf, Till Westmann, Markos Zaharioudakis

Version Declaration

xquery version "3.0" encoding "utf-8";

Namespaces

anhttp://zorba.io/annotations
dmlhttp://zorba.io/modules/store/dynamic/collections/dml
verhttp://zorba.io/options/versioning
zerrhttp://zorba.io/errors

Function Summary

insert-before($name as xs:QName, $target as item(), $content as item()*) external

Inserts copies of the given items (nodes or JSON items) into a collection at the position directly preceding the given target item.

insert-first($name as xs:QName, $content as item()*) external

Inserts copies of the given items (nodes or JSON items) at the beginning of the collection.

insert-last($name as xs:QName, $content as item()*) external

Inserts copies of the given items (nodes or JSON items) at the end of the collection.

insert-after($name as xs:QName, $pos as item(), $content as item()*) external

Inserts copies of the given items (nodes or JSON items) into a collection at the position directly following the given target item.

apply-insert-first($name as xs:QName, $content as item()*) as item()* external

This function does the same thing as insert-first() except it immediately applies the resulting pending updates and returns the items that have been inserted.

apply-insert-last($name as xs:QName, $content as item()*) as item()* external

This function does the same thing as insert-last() except it immediately applies the resulting pending updates and returns the items that have been inserted.

apply-insert-before($name as xs:QName, $target as item(), $content as item()*) as item()* external

This function does the same thing as insert-before() except it immediately applies the resulting pending updates and returns the items that have been inserted.

apply-insert-after($name as xs:QName, $target as item(), $content as item()*) as item()* external

This function does the same thing as insert-after() except it immediately applies the resulting pending updates and returns the items that have been inserted.

collection($name as xs:QName) as item()* external

Gets the sequence of nodes or JSON items from a collection.

collection($name as xs:QName, $skip as xs:integer) as item()* external

Gets the sequence of items (nodes or JSON items) from a collection.

collection($name as xs:QName, $start as xs:anyURI, $skip as xs:integer) as item()* external

Gets the sequence of items (nodes or JSON items) from a collection.

collection-name($item as item()) as xs:QName external

Gets the name of the collection the given item (node or JSON item) belongs to.

delete($items as item()*) external

Deletes items (nodes or JSON items) from a collection.

delete-first($name as xs:QName) external

Deletes the first item from a collection.

delete-first($name as xs:QName, $number as xs:integer) external

Deletes the first N items from a collection.

delete-last($name as xs:QName) external

Deletes the last item from a collection.

delete-last($name as xs:QName, $number as xs:integer) external

Deletes the last N items from a collection.

edit($target as item(), $content as item()) external

Edits the first supplied item so as to make it look exactly like a copy of the second supplied item while retaining its original identity.

index-of($item as item()) as xs:integer external

Gets the position of the given item (node or JSON item) within its collection.

truncate($name as xs:QName) external

Deletes the entire contents of a collection.

Functions

insert-before#3

declare updating function dml:insert-before(
    $name as xs:QName,
    $target as item(),
    $content as item()*
) as item()* external

Inserts copies of the given items (nodes or JSON items) into a collection at the position directly preceding the given target item.

Parameters

  • $name

    The name of the collection to insert into.

  • $target

    The item in the collection before which $content will be inserted.

  • $content

    The sequence of items whose copies to insert.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0011

    if $target is not in the collection.

insert-first#2

declare updating function dml:insert-first(
    $name as xs:QName,
    $content as item()*
) as item()* external

Inserts copies of the given items (nodes or JSON items) at the beginning of the collection.

Parameters

  • $name

    The name of the collection to insert into.

  • $content

    The sequence of items whose copies to insert.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

insert-last#2

declare updating function dml:insert-last(
    $name as xs:QName,
    $content as item()*
) as item()* external

Inserts copies of the given items (nodes or JSON items) at the end of the collection.

Parameters

  • $name

    The name of the collection to insert into.

  • $content

    The sequence of items whose copies to insert.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

insert-after#3

declare updating function dml:insert-after(
    $name as xs:QName,
    $pos as item(),
    $content as item()*
) as item()* external

Inserts copies of the given items (nodes or JSON items) into a collection at the position directly following the given target item.

Parameters

  • $name

    The name of the collection to insert into.

  • $target

    The item in the collection after which $content will be inserted.

  • $content

    The sequence of items whose copies to insert.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0011

    if $target is not in the collection.

apply-insert-first#2

declare %an:sequential function dml:apply-insert-first(
    $name as xs:QName,
    $content as item()*
) as item()* external
This function does the same thing as insert-first() except it immediately applies the resulting pending updates and returns the items that have been inserted.

Parameters

  • $name

    The name of the collection to insert into.

  • $content

    The sequence of items whose copies to insert.

Returns

  • item()*

    The sequence of items that have been inserted.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

apply-insert-last#2

declare %an:sequential function dml:apply-insert-last(
    $name as xs:QName,
    $content as item()*
) as item()* external
This function does the same thing as insert-last() except it immediately applies the resulting pending updates and returns the items that have been inserted.

Parameters

  • $name

    The name of the collection to insert into.

  • $content

    The sequence of items whose copies to insert.

Returns

  • item()*

    The sequence of items that have been inserted.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

apply-insert-before#3

declare %an:sequential function dml:apply-insert-before(
    $name as xs:QName,
    $target as item(),
    $content as item()*
) as item()* external
This function does the same thing as insert-before() except it immediately applies the resulting pending updates and returns the items that have been inserted.

Parameters

  • $name

    The name of the collection to insert into.

  • $target

    The item in the collection before which $content will be inserted.

  • $content

    The sequence of items whose copies to insert.

Returns

  • item()*

    The sequence of items that have been inserted.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

apply-insert-after#3

declare %an:sequential function dml:apply-insert-after(
    $name as xs:QName,
    $target as item(),
    $content as item()*
) as item()* external
This function does the same thing as insert-after() except it immediately applies the resulting pending updates and returns the items that have been inserted.

Parameters

  • $name

    The name of the collection to insert into.

  • $target

    The item in the collection after which $content will be inserted.

  • $content

    The sequence of items whose copies to insert.

Returns

  • item()*

    The sequence of items that have been inserted.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0011

    if $target is not in the collection.

collection#1

declare function dml:collection(
    $name as xs:QName
) as item()* external

Gets the sequence of nodes or JSON items from a collection.

Parameters

  • $name

    The name of the collection.

Returns

  • item()*

    The sequence contained in the given collection.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

collection#2

declare function dml:collection(
    $name as xs:QName,
    $skip as xs:integer
) as item()* external

Gets the sequence of items (nodes or JSON items) from a collection.

Parameters

  • $name

    The name of the collection.

  • $skip

    The number of collection items to skip.

Returns

  • item()*

    The sub-sequence contained in the given collection.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

collection#3

declare function dml:collection(
    $name as xs:QName,
    $start as xs:anyURI,
    $skip as xs:integer
) as item()* external
Gets the sequence of items (nodes or JSON items) from a collection. The parameters $start and $skip can be used to skip over items at the beginning of the collection. If both are given, both are applied: first, $start to skip to that item and then $skip to skip that additional number of items.

Parameters

  • $name

    The name of the collection.

  • $start

    A reference to the first item to return.

  • $skip

    The additional number of items to skip.

Returns

  • item()*

    The sub-sequence from the given collection.

Errors

  • zerr:ZAPI0028

    If the given URI is not a valid node position computed by the np:node-position function.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZSTR0066

    If $start does not reference a node from the collection $name.

collection-name#1

declare function dml:collection-name(
    $item as item()
) as xs:QName external

Gets the name of the collection the given item (node or JSON item) belongs to.

Parameters

  • $item

    The item for which to get the name of the collection.

Returns

  • xs:QName

    The name of the collection to which $item belongs.

Errors

  • zerr:ZDDY0011

    if $item does not belong to a collection.

delete#1

declare updating function dml:delete(
    $items as item()*
) as item()* external

Deletes items (nodes or JSON items) from a collection.

Parameters

  • $items

    The items in the collection to delete.

Errors

  • zerr:ZDDY0011

    if any item in $items is not a member of a collection or not all items belong to the same collection.

delete-first#1

declare updating function dml:delete-first(
    $name as xs:QName
) as item()* external

Deletes the first item from a collection.

Parameters

  • $name

    The name of the collection to delete from.

Errors

  • zerr:ZDDY0011

    if the collection is empty.

delete-first#2

declare updating function dml:delete-first(
    $name as xs:QName,
    $number as xs:integer
) as item()* external
Deletes the first N items from a collection.

Parameters

  • $name

    The name of the collection to delete from.

  • $number

    The number of items to delete.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0011

    if the collection contains less than $number items.

delete-last#1

declare updating function dml:delete-last(
    $name as xs:QName
) as item()* external

Deletes the last item from a collection.

Parameters

  • $name

    The name of the collection to delete from.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0011

    if the collection is empty.

delete-last#2

declare updating function dml:delete-last(
    $name as xs:QName,
    $number as xs:integer
) as item()* external
Deletes the last N items from a collection.

Parameters

  • $name

    The name of the collection to delete from.

  • $number

    The number of items to delete.

Errors

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0011

    if the collection contains less than $number items.

edit#2

declare updating function dml:edit(
    $target as item(),
    $content as item()
) as item()* external

Edits the first supplied item so as to make it look exactly like a copy of the second supplied item while retaining its original identity.

Parameters

  • $target

    The target item to be edited.

  • $content

    The item that serves as an edit goal.

Errors

  • zerr:ZDDY0003

    if the collection to which $target belongs is not available.

  • zerr:ZDDY0006

    if the collection to which $target belongs is append-only, const, or queue.

  • zerr:ZDDY0017

    if $target is not a member of a collection.

  • zerr:ZDDY0037

    if the collection is append-only.

  • zerr:ZDDY0038

    if the collection is a queue.

  • zerr:ZDDY0039

    if $target is not a root.

  • zerr:ZDDY0040

    if $target cannot be updated to match the content (for example, because the target is a node and the content is an object).

index-of#1

declare function dml:index-of(
    $item as item()
) as xs:integer external

Gets the position of the given item (node or JSON item) within its collection.

Parameters

  • $item

    The item to get the index of.

Returns

  • xs:integer

    The position of $item in its collection.

Errors

  • zerr:ZDDY0011

    if $item does not belong to a collection.

truncate#1

declare updating function dml:truncate(
    $name as xs:QName
) as item()* external

Deletes the entire contents of a collection.

Parameters

  • $name

    The name of the collection whose contents to delete.

Errors

  • zerr:ZDDY0003

    if the collection is not available.