XQuery Functions Reusing XQuery Code Date: September, 2008 Dan McCreary President Dan McCreary & Associates [email protected] m (952) 931-9198 M D Metadata Solutions
Jan 13, 2016
XQuery FunctionsReusing XQuery CodeDate: September, 2008
Dan McCrearyPresidentDan McCreary & [email protected](952) 931-9198
M
D
Metadata Solutions
M
D Copyright 2007 Dan McCreary & Associates2
Overview
• Why use functions?• XQuery Built-in functions• eXist-specific functions• How to define functions• Passing parameters• Function signatures• Recursive functions
M
D Copyright 2007 Dan McCreary & Associates3
Why Use Functions?
• To reuse snippets of your code
• To make code easier to maintain
• To make code easier to read
M
D Copyright 2007 Dan McCreary & Associates4
Function Layers
Base XQuery 1.0 Functions
eXistUpdate
XQueryUpdate 1.0
eXist built-inFunctions
PublicFunctions
Your Custom Functions
eXist Extensions
future
M
D Copyright 2007 Dan McCreary & Associates5
eXist Function Documentation
• eXist has around 384 functions
• tools for searching built in to each installation
M
D Copyright 2007 Dan McCreary & Associates 6
eXist Function Documentation Tool
M
D Copyright 2007 Dan McCreary & Associates7
Common XQuery Built-in Functions• functions for getting data
– doc, collection• numeric functions
– abs, avg, ceiling, floor, max, min, number, round, round-half-to-even, sum• date and time functions
– current-dateTime, current-date, current-time, implicit-timezone• set functions
– distinct-values, starts-with, deep-equal, empty, subsequence• common string functions:
– concat, lower-case, substring, substring-before, substring-after, string-join, upper-case
• logic– boolean, not, false, true
• uri-functions– base-uri, document-uri, namespace-uri, namespace-uri-for-prefix
M
D Copyright 2007 Dan McCreary & Associates8
Common eXist Built-in Extensions
• request – processing incoming HTTP requests– create-session, get-parameter, get-data, get-session, get-context-path, get –
cookie-names, get-cookie-value, get-header, get-hostname, get-method, get-server-port
• response – Setting outgoing HTTP responses– redirect, set-cookie, set-header, set-status-code
• xmldb– create collection, store, move, copy, change permissions, created, get-child-
collections, remove, rename• update
– insert, update, replace, rename, delete• session
– manage session variables• system
– get system status like build number, memory-free or index data• text – filter, fuzzy-match-all, fuzzy-match-any, highlight-matches, kwic-
display, match-all, match-any• ngram – full-text indexing contains, starts-with, ends-with, matches• util – call, binary-doc, complie, eval, exclusive-lock, index-keys, log-system-
out, random
M
D Copyright 2007 Dan McCreary & Associates9
Other eXist Extension Modules
• E-mail – send an e-mail to a person from the result of an XQuery
• Scheduler – schedule reports to run at intervals• Compression – compress files• Math – advanced math functions• Image Management – generate thumbnail images
etc.• XML Differences – report on how XML files differ• GML – Geography Markup Language
Note: These need to be configured by the eXist systems administrator.
M
D Copyright 2007 Dan McCreary & Associates10
URI functions
• base-uri, document-uri, static-base-uri, document-uri, iri-to-uri
M
D Copyright 2007 Dan McCreary & Associates11
Math and Set Functions
• floor
• exists
• insert-before
• insert-after
M
D Copyright 2007 Dan McCreary & Associates12
NGram
• contains – does a full-text string contain a specific string?
• starts-with, ends-with – does a full-text string start or end start with a string?
• filter-matches – exclude specific results from a match
http://exist-db.org/xquery/ngram
M
D Copyright 2007 Dan McCreary & Associates13
How to Define a Function
declare function local:my-function() as return-type {
…your code here
return
<result/>
};
M
D Copyright 2007 Dan McCreary & Associates14
Hello World Function
declare function local:hello-world() as xs:string {
let $message := 'Hello World'
return
$message
};
• The "local" namespace• Can not be called outside of this XQuery file
• No input parameters• A single string as an output parameter
M
D Copyright 2007 Dan McCreary & Associates15
How to Call a Function
xquery version "1.0";
declare function local:hello-world() as xs:string { let $message := 'Hello World' return $message};
let $my-variable := local:hello-world()
You must use the "local:" prefix.
M
D
String Processing Example
Copyright 2011 Dan McCreary & Associates16
• Write a function that returns the "database path" to your current location.
• Input:– '/exist/rest/db/apps/faqs/views/my-query.xq
• Output:– '/db/apps/faqs'
M
D Copyright 2007 Dan McCreary & Associates17
Input and Output Parameters
xquery version "1.0";
declare function local:app-base-collection($uri as xs:string) as xs:string { let $app-base := substring-before(substring-after($uri, '/exist/rest'), '/views/') return $app-base};
let $uri := '/exist/rest/db/apps/faqs/views/my-query.xq'
return<results> <app-base-collection>{local:app-base-collection($uri)}</app-base-collection></results>
<results> <app-base-collection>/db/apps/faqs</app-base-collection></results>
Use a string as input and get a string as output.
M
D Copyright 2007 Dan McCreary & Associates 18
Get the Base Collectionxquery version "1.0";
declare function local:app-base-collection() as xs:string { let $app-base := concat('/db/', substring-before(substring-after(request:get-uri(), '/exist/rest/db/'), '/')) return $app-base};
return<results> <uri>{request:get-uri()}</uri> <app-base-collection>{local:app-base-collection()}</app-base-collection></results>
Note that this will not work from within oXygen, only from the web browser.
<results> <uri>/exist/rest/db/xrx-training/labs/02-functions/app-base-collection.xq </uri> <app-base-collection>/db/xrx-training</app-base-collection></results>
Output:
M
D Copyright 2007 Dan McCreary & Associates19
Passing Parameters
• You can pass many parameters into any function but functions usually return only a simple type or a complex element
• Each parameter has a “cardinality” that describes if it is an optional parameter (may be null), or has more then one value.
Note: checking parameters is a great way to test the data for your functions
M
D
Cardinality Specifiiers
• The following notation is used to describe the cardinality of each parameter:
none a single required parameter? an optional single parameter
* zero to many parameter
+ One to many parameters
Also called the "arity" of a function
Copyright 2011 Dan McCreary & Associates20
M
D
Labs
• Create your own function that will capitalize the first letter of a word– Use the substring($in, 1, 1) function to get the
first character– Use the upper-case() function to convert to
upper case
• Create a second function to capitalize all the first letter in a sentence– Use the tokenize() function to separate a
sentence into a sequence of words
Copyright 2007 Dan McCreary & Associates21
M
D
Lab Description:
• Create an XQuery function that will return the “title case” of a string.
Input:
the quick brown fox jumps over the lazy dog
Output:
The Quick Brown Fox Jumps Over The Lazy Dog
Copyright 2011 Dan McCreary & Associates22
M
D
Labs
• Title Case Lab• https://docs.google.com/document/pub?id=15_CZ8sHjd_yGC2B83oKGCIQtXQJtqyowy7v3KtSzbvc
Copyright 2011 Dan McCreary & Associates23