Changes

Jump to navigation Jump to search
6,488 bytes added ,  15:32, 27 February 2020
no edit summary
==Introduction==In BaseX, there are two kinds of databases. It This page is possible to havedatabases with single XML documents and databases with a bunch part of XML files, called ''Collections''the [[Getting Started]] Section.
===Creation of In BaseX, a ''database===You can create '' is a pretty light-weight concept. It may contain one or more '''resources''', which are addressed by a unique database either within path. There is no explicit layer for collections: Instead, collections are implicitly created and deleted, and collections result from the GUI or existence of documents in the console version of BaseXspecific paths. *[[Startup#BaseX GUI|GUI]]: Go to Resources can either be '''XML documents'''Databaseor '' 'raw files'New'' and then press Browse to choose a file and press OK *(binaries). Some information on [[Startup#BaseX StandaloneBinary Data|Consolebinary data]]: enter <code>basex -c "CREATE DB dbname /path/to/file"</code><br/>can be found on an extra page.
==Collection== Multiple databases can be addressed (queries, updated) with a single XQuery expression. As a single database is restricted to 2 billion nodes (see [[Statistics]]), resources can be distributed across multiple database instances.
=Create Databases==Creation of a collection===You can create a collection either within the GUI or in the console version of BaseX. *GUI: Go to ''Database'' → ''New'' and then press Browse to choose a directory and press OK *Console: enter <code>basex -c "CREATE DB dbname /path/to/collection"</code><br/>
===Manage Collections=== Additional to Databases can be created via commands, via XQuery, in the creation with your choosen xml files you can start GUI, or with creating an emptycollection and then add your xml files to it. Note that the <code>any of our [[Commands#ADDDeveloping|ADDAPIs]]</code>and <code>[[Commands#DELETE|DELETE]]</code> commands refer . If an initial input is specified with create, some time can be saved, as the specified resources will be added to the currently opened database. in a bulk operation:
* [[Startup#BaseX Standalone|Console:* Create an empty database]]: <code>CREATE DB exampledb /path/to/resources</code> * Add will add initial documents to a document: <code>ADD example.xml</code> database* Delete a document[[Startup#BaseX GUI|GUI]]: <code>DELETE example.xml</code> Go to ''Database'' → ''New'', press ''Browse'' to choose an initial file or directory, and press ''OK''
GUI:In the GUI you The name of a database is restricted to a restricted set of characters (see [[Valid Names]]). Various [[parsers]] can execute all above operations in be chosen to control the Database menuimport process, or to convert different formats to XML.
Once you have '''Note:''' A main-memory database will be created a database, you may as well use if the BaseX-specific {{Option|MAINMEM}} option is enabled ([[Databases#In Memory Database Functions|XQuery Database Functionssee below]] to add or delete XML documents:for more).
<pre class="brush:xquery">for $file in file:list("/path/to/xml/documents")return db:add("database", $file)</pre>Access Resources=
===Access Stored resources and external documents in collections===The XQuery <code>collection()</code> function can be used to access documents in collections: *Returning all documents of collection ("dbname"):<br/> <code>for $doc in collection("dbname") return base-uri($doc)</code> *Access a specific document ("test") accessed in collection ("dbname")different ways:<br/> <code>collection("dbname/test")//*</code>
==XML Documents== Various XQuery functions exist to access XML documents in databases: {| class="wikitable"|-!Function!Example!Description|-|[[Database Module#db:open|db:open]]|{{Code|db:open("db", "path/to/docs")}}|Returns all documents that are found in the database {{Code|db}} at the (optional) path {{Code|path/to/docs}}.|-|[http://www.xqueryfunctions.com/xq/fn_collection.html fn:collection]|{{Code|collection("db/path/to/docs")}}|Returns all documents at the location {{Code|path/to/docs}} in the database {{Code|db}}.<br/>If no path is specified after the database, all documents in the database will be returned.<br/>If no argument is specified, all documents of the database will be returned that has been opened in the global context.|-|[http://www.xqueryfunctions.com/xq/fn_doc.html fn:doc]|{{Code|doc("db/path/to/doc.xml")}}|Returns the document at the location {{Code|path/to/docs}} in the database {{Code|db}}.<br/>An error is raised if the specified yields zero or more than one document.|} You can access multiple databases in a single query: <syntaxhighlight lang="xquery">for $i in 1 to 100return db:open('books' || $i)//book/title</syntaxhighlight> If the {{Option|DEFAULTDB}} option is turned on, the path argument of the {{Code|fn:doc}} or {{Code|fn:collection}} function will first be resolved against the globally opened database. Two more functions are available for retrieving information on database nodes: {| class="wikitable"|-!Function!Example!Description|-|[[Database Module#db:name|db:name]]|{{Code|db:name($node)}}|Returns the name of the database in which the specified {{Code|$node}} is stored.|-|[[Database Module#db:path|db:path]]|{{Code|db:path($node)}}|Returns the path of the database document in which the specified {{Code|$node}} is stored.|} The {{Code|fn:document-uri}} and {{Code|fn:base-uri}} functions return URIs that can also be reused as arguments for the {{Code|fn:doc}} and {{Code|fn:collection}} functions. As a result, the following example query always returns {{Code|true}}: <syntaxhighlight lang="xquery">every $c in collection('anyDB')satisfies doc-available(document-uri($c))</syntaxhighlight> If the argument of {{Code|fn:doc}} or {{Code|fn:collection}} does not start with a valid database name, or if the addressed database does not exist, the string is interpreted as URI reference, and the documents found at this location will be returned. Examples: * {{Code|doc("http://web.de")}}: retrieves the addressed URI and returns it as a main-memory document node.* {{Code|doc("myfile.xml")}}: retrieves the given file from the file system and returns it as a main-memory document node. Note that updates to main-memory nodes are not automatically written back to disk unless the {{Option|WRITEBACK}} option is set.* {{Code|collection("/path/to/docs")}}: returns a main-memory collection with all XML documents found at the addressed file path. ==Raw Files== The <code>[[Commands#RETRIEVE|RETRIEVE]]</code> command and the <code>[[Database Module#db:retrieve|db:retrieve]]</code> function can be used to return files in their native byte representation. If the API you use does not support binary output (this is e.g. the case for various [[Clients|Client]] language bindings), you need to convert your binary data to its string representation before returning it to the client: <syntaxhighlight lang="xquery">string(db:retrieve('multimedia', 'sample.avi'))</syntaxhighlight> ==HTTP Services== * With [[REST]] and [[WebDAV]], all database resources can be requested in a uniform way, no matter if they are well-formed XML documents or binary files. =Update Resources= Once you have created a database, additional commands exist to modify its contents: * XML documents can be added with the <code>[[Commands#ADD|ADD]]</code> command.* Raw files are added with <code>[[Commands#STORE|STORE]]</code>.* Existing resources can be replaced with the <code>[[Commands#REPLACE|REPLACE]]</code> command.* Resources can be deleted via <code>[[Commands#DELETE|DELETE]]</code>. The {{Option|AUTOFLUSH}} option can be turned off before ''bulk operations'' (i.e. before a large number of new resources is added to the database). If {{Option|ADDCACHE}} is enabled, the input will be cached before it is added to the database. This is helpful when the input documents to be added are expected to consume too much main memory. The following commands create an empty database, add two resources, explicitly flush data structures to disk, and finally delete all inserted data: <syntaxhighlight>CREATE DB exampleSET AUTOFLUSH falseADD example.xmlSET ADDCACHE trueADD /path/to/xml/documentsSTORE TO images/ 123.jpgFLUSHDELETE /</syntaxhighlight> You may also use the BaseX-specific [[CategoryDatabase Module|XQuery Database Functions]] to create, add, replace, and delete XML documents: <syntaxhighlight lang="xquery">let $root := "/path/to/xml/documents/"for $file in file:list($root)return db:Beginneradd("database", $root || $file)</syntaxhighlight> Last but not least, XML documents can also be added via the GUI and the ''Database'' menu. =Export Data= All resources stored in a database can be ''exported'', i.e., written back to disk. This can be done in several ways: * Commands: <code>[[Commands#EXPORT|EXPORT]]</code> writes all resources to the specified target directory* GUI: Go to ''Database'' → ''Export'', choose the target directory and press ''OK''* WebDAV: Locate the database directory (or a sub-directory of it) and copy all contents to another location =Main-Memory Database Instances= * In the standalone context, a main-memory database can be created (using <code>CREATE DB</code>), which can then be accessed by subsequent commands.* If a BaseX server instance is started, and if a database is created in its context (using <code>CREATE DB</code>), other BaseX client instances can access (and update) this database (using OPEN, db:open, etc.) as long as no other database is opened/created by the server.* You can force an ordinary database to being copied to memory by using <code>db:open('some-db') update {}</code> '''Note:''' If you address a URI with <code>fn:doc</code> or <code>fn:collection</code> for which no database exists, the resulting internal representation is identical to those of main-memory database instances (no matter which value is set for {{Option|MAINMEM}}). =Changelog= ;Version 8.4 * Updated: [[#Raw Files|Raw Files]]: Items of binary type can be output without specifying the obsolete <code>raw</code> serialization method. ;Version 7.2.1 * Updated: {{Code|fn:document-uri}} and {{Code|fn:base-uri}} now return strings that can be reused with {{Code|fn:doc}} or {{Code|fn:collection}} to reopen the original document.
Bureaucrats, editor, reviewer, Administrators
13,550

edits

Navigation menu