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

Description

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

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

This module is part of Zorba's XQuery Data Definition Facility. All the collections managed by this module have to be pre-declared in the prolog of a module. Please refer to the general documentation for more information and examples.

Module code

Here is the actual XQuery module code.

See also

Authors

Nicolae Brinza, Matthias Brantner, David Graf, Till Westmann, Markos Zaharioudakis

Version Declaration

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

Namespaces

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

Function Summary

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 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.

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

Inserts copies of the given items (nodes or JSON items) into a collection.

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

The insert-after function is an updating function that inserts copies of the given items (nodes or JSON items) into a collection at the position directly following the given target item.

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 a 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 a collection.

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

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

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, $pos as item(), $content as item()*) as item()* external

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

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.

truncate($name as xs:QName) external

Deletes the entire contents of 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.

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

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

Functions

collection#1

declare function cdml: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 seqnence of items from the collection.

Errors

  • zerr:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

collection#2

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

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

Parameters

  • $name

    The name of the collection.

  • $skip

    The initial number of items to skip.

Returns

  • item()*

    The (sub)sequence of items from the collection.

Errors

  • zerr:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

collection#3

declare function cdml: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 some items at the beginning of the collection. If both are given, both are applied: first $start to skip to the referenced item and then $skip to skip that additional number of items.

Parameters

  • $name

    The name of the collection.

  • $start

    The reference to the first item to return.

  • $skip

    The number of additional items to skip.

Returns

  • item()*

    The sub-sequence from the collection.

Errors

  • zerr:ZAPI0028

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

  • zerr:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZSTR0066

    if $start does not reference a node from the collection.

insert#2

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

Inserts copies of the given items (nodes or JSON items) into a collection. Note that the insertion position of the items in the collection is not defined.

Parameters

  • $name

    The name of the collection to insert into.

  • $content

    The sequence of items whose copies to insert.

Errors

  • zerr:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is append-only, const, or queue.

  • zerr:ZDTY0001

    if $content does not match the expected type as specified in the collection declaration according to the rules for SequenceType Matching.

insert-after#3

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

The insert-after function is an updating function that 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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is const, append-only, or queue.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDTY0001

    if $content does not match the expected type as specified in the collection declaration according to the rules for SequenceType Matching.

  • zerr:ZDDY0011

    if $target is not a node that is contained in the collection.

insert-before#3

declare updating function cdml: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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is const, append-only, or queue.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDTY0001

    if $content does not match the expected type as specified in the collection declaration according to the rules for SequenceType Matching.

  • zerr:ZDDY0011

    if $target is not an item that is contained in the collection.

insert-first#2

declare updating function cdml: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 a collection.

Parameters

  • $name

    The name of the collection to insert into.

  • $content

    The sequence of items whose copies to insert.

Errors

  • zerr:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is append-only, const, or queue.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDTY0001

    if $content does not match the expected type as specified in the collection declaration according to the rules for SequenceType Matching.

insert-last#2

declare updating function cdml: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 a collection.

Parameters

  • $name

    The name of the collection to insert into.

  • $content

    The sequence of itemss whose copies to insert.

Errors

  • zerr:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is const.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDTY0001

    if $content does not match the expected type as specified in the collection declaration according to the rules for SequenceType Matching.

apply-insert#2

declare %an:sequential function cdml:apply-insert(
    $name as xs:QName,
    $content as item()*
) as item()* external
This function does the same thing as insert() 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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is append-only, const, or queue.

  • zerr:ZDTY0001

    if $content does not match the expected type as specified in the collection declaration according to the rules for SequenceType Matching.

apply-insert-first#2

declare %an:sequential function cdml: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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection $name is append-only, const, or queue.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDTY0001

    if $content does not match the expected type as specified in the collection declaration according to the rules for SequenceType Matching.

apply-insert-last#2

declare %an:sequential function cdml: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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is const.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDTY0001

    if $content does not match the expected type as specified in the collection declaration according to the rules for SequenceType Matching.

apply-insert-before#3

declare %an:sequential function cdml: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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection $name is const, append-only, or queue.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDTY0001

    if $content does not match the expected type as specified in the collection declaration according to the rules for SequenceType Matching.

  • zerr:ZDDY0011

    if $target is not an item that is contained in the collection.

apply-insert-after#3

declare %an:sequential function cdml:apply-insert-after(
    $name as xs:QName,
    $pos as item(),
    $content as item()*
) as item()* external
This function does the same thing as the insert-after() function 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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is const, append-only, or queue.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDTY0001

    if $content does not match the expected type as specified in the collection declaration according to the rules for SequenceType Matching.

  • zerr:ZDDY0011

    if $target is not in the collection.

delete#1

declare updating function cdml: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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is const, append-only, or queue.

  • 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 cdml: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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is const or append-only.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDDY0011

    if the collection is empty.

delete-first#2

declare updating function cdml: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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is const or append-only.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDDY0011

    if the collection contains less than $number items.

delete-last#1

declare updating function cdml: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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0006

    if the collection is const, append-only, or queue.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDDY0011

    if the collection is empty.

delete-last#2

declare updating function cdml: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:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

  • zerr:ZDDY0012

    if the collection is unordered.

  • zerr:ZDDY0011

    if the collection contains less than $number items.

edit#2

declare updating function cdml: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:ZDDY0001

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

  • 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).

  • zerr:ZDTY0001

    if $content does not match the expected type (as specified in the collection declaration) according to the rules for SequenceType Matching.

truncate#1

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

Deletes the entire contents of collection. Please note that applying this function can not be undone in case an error happens during the application of the containing PUL.

Parameters

  • $name

    The name of the collection whose content to delete.

Errors

  • zerr:ZDDY0001

    if the collection is not declared.

  • zerr:ZDDY0003

    if the collection is not available.

collection-name#1

declare function cdml: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 its collection.

Returns

  • xs:QName

    The name of the collection to which the given item belongs.

Errors

  • zerr:ZDDY0011

    if $item does not belong to a collection.

index-of#1

declare function cdml: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.

  • zerr:ZDDY0012

    if the collection is unordered.