Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
Multiple On command line, multiple commands can be written down in a single line – (separated by semicolons – or ). You can also put them into a command script: Database commands in both string and XML syntax can be placed in a text file and stored as file with the BaseX command script suffix {{Code|.bxs}}. If the path to a script file is passed on to BaseX on command-line, or if it is opened in the GUI editor, it will be recognized and evaluated as such.
* <code>.</code>: hidden folders (e.g. the [[Logging|.logs directory]])
=Administration=
* <code>EXECUTE "create db db1; create db db2"</code><br/>* <code>EXECUTE "<commands><create-db name='db1'/><create-db name='db2'/></commands>"</code><br/>both commands Two databases will create two databases {{Code|db1}} and {{Code|db2}} be created in a single transaction.
no edit summary
==Command Scripts==
===String Syntax===
Lines starting with <code>#</code> are interpreted as comments and are skipped. With the following script, a database is created, two documents are added to it, and a query is performed:
<pre classsyntaxhighlight lang="brush:xml">
CREATE DB test
ADD TO embedded.xml <root>embedded</root>
XQUERY <hits>{ count(//text()) }</hits>
CLOSE
</presyntaxhighlight>
===XML Syntax===
The XML syntax provides more flexibility here. Multiple commands can be enclosed by a {{Code|<commands/>}} root element. Some commands, such as {{Command|ADD}}, allow you to directly embed XML documents. If you want to embed XML in XQuery expressions, entities should be encoded, or the {{Code|CDATA}} syntax should be used:
<pre classsyntaxhighlight lang="brush:xml">
<commands>
<create-db name='test'/>
<close/>
</commands>
</presyntaxhighlight>
==Glob Syntax==
* <code>;</code>: Separator for multiple database commands on the [[Command-Line Options|command line]]
* <code>\/</code>: Directory path separators
* <code>:*?\"<>|}</code>: invalid filename characters on Windows
* Names starting or ending with <code>.</code>: hidden folders (e.g. the [[Logging|.logs directory]])
==Aliases==
|-
| '''Summary'''
|Creates a new database with the specified {{Code|name}} and, optionally, an initial {{Code|input}}, and opens it. An existing database will be overwritten.<br />The input may either can be a reference file or directory path to a single XML document, a directorydocuments, a remote URL, or a string containing XML:
* {{Code|name}} must be a [[#Valid Names|valid database name]]
* database creation can be controlled by setting [[Options#Create Options|Create Options]]
If you need to add initial resources, it is always faster to supply them at creation time than adding them in a subsequent step via {{Command|ADD}}.
|-
| '''Errors'''
* {{Code|CREATE DB xmark http://files.basex.org/xml/xmark.xml}}<br/>creates the database {{Code|xmark}}, containing a single initial document called {{Code|xmark.xml}}.
* {{Code|CREATE DATABASE coll /path/to/input}}<br/>creates the database {{Code|coll}} with all documents found in the {{Code|input}} directory.
* {{Code|SET INTPARSE false; }} and {{Code|CREATE DB input input.xml}}<br/>creates a database {{Code|input}} with {{Code|input.xml}} as initial document, which will be parsed with Java's [[Parsers#XML Parsers|default XML parser]].
* <code><create-db name='simple'><hello>Universe</hello></create-db></code><br/>creates a database named {{Code|simple}} with an initial document {{Code|<hello>Universe</hello>}}.
|}
|-
| '''Summary'''
|This convenience command combines {{Command|OPEN}} and {{Command|CREATE DB}}: if If a database with the name {{Code|input}} exists, it and if there is no existing file or directory with the same name that has a newer timestamp, the database is opened. Otherwise, a new database is created; if the specified input points to an existing resource, it is stored as initial content.
|-
| '''Errors'''
|The command fails if no database is opened, if the specified index is unknown, or if it could not be deleted for some other reason.
|}
==ALTER DB==
|}
==CREATE BACKUPCOPY==
{| width='100%'
|-
|width='130'|'''Syntax'''
|{{Code|CREATE BACKUP COPY [name] [newname]}}
|-
| '''XML Syntax'''
|<code><create-backup copy name='...' newname='...'/></code><br/>
|-
| '''Permission'''
|-
| '''Summary'''
|Creates a zipped backup copy of the database specified by {{Code|name}}. The backup file will {{Code|newname}} must be suffixed with the current timestamp and stored in the database directory. The a [[#Glob SyntaxValid Names|Glob Syntaxvalid database name]] can be used to address more than one database.
|-
| '''Errors'''
|The command fails if the specified target database does not existalready exists, or if it could not be zipped for some other reason.|-| '''Examples'''|* {{Code|BACKUP db}}<br/>creates a zip archive of the source database {{Code|db}} (e.g. {{Code|db-2014-04-01-12-27-28.zip}}) in the [[Configuration#Database_Directory|database directory]]does not exist.
|}
=Administration=RESTORE ==CREATE BACKUP==
{| width='100%'
|-
|width='130'|'''Syntax'''
|{{Code|RESTORE CREATE BACKUP [name]}}
|-
| '''XML Syntax'''
|<code><restore create-backup name='...'/></code><br/>
|-
| '''Permission'''
|-
| '''Summary'''
|Restores Creates a zipped backup of the database with the specified by {{Code|name}}. The name may include backup file will be suffixed with the current timestamp of and stored in the backup filedatabase directory. The [[#Glob Syntax|Glob Syntax]] can be used to address more than one database.
|-
| '''Errors'''
|The command fails if the specified backup database does not exist, if the database to be restored is currently locked, or if it could not be restored zipped for some other reason.|-| '''Examples'''|* {{Code|BACKUP db}}<br/>creates a zip archive of the database {{Code|db}} (e.g. {{Code|db-2014-04-01-12-27-28.zip}}) in the [[Configuration#Database_Directory|database directory]].
|}
==INSPECTDROP BACKUP==
{| width='100%'
|-
|width='130'|'''Syntax'''
|{{Code|INSPECTDROP BACKUP [name]}}
|-
| '''XML Syntax'''
|<code><inspectdrop-backup name='...'/></code><br/>
|-
| '''Permission'''
|''READCREATE''
|-
| '''Summary'''
|Performs some integrity checks on Drops all backups of the opened database and returns a brief summarywith the specified {{Code|name}}. The [[#Glob Syntax|Glob Syntax]] can be used to address more than one database.|-| '''Examples'''|* {{Code|DROP BACKUP abc*}}<br/>deletes the backups of all databases starting with the characters {{Code|abc}}.
|}
==DROP ALTER BACKUP==
{| width='100%'
|-
|width='130'|'''Syntax'''
|{{Code|DROP ALTER BACKUP [name] [newname]}}
|-
| '''XML Syntax'''
|<code><dropalter-backup name='...' newname='...'/></code><br/>
|-
| '''Permission'''
|-
| '''Summary'''
|Drops Renames all backups of the database with the specified {{Code|name}}to {{Code|new-name}}. The directory inside the archive will be renamed as well. The [[#Glob Syntax|Glob Syntax]] can be used to address more than one database.
|-
| '''Examples'''
|
* {{Code|DROP ALTER BACKUP abc*logs logs-backup}}<br/>deletes renames the backups of all databases starting with the characters {{Code|abclogs}} database to {{Code|logs-backup}}.
|}
|}
==COPYRESTORE==
{| width='100%'
|-
|width='130'|'''Syntax'''
|{{Code|COPY RESTORE [name] [newname]}}
|-
| '''XML Syntax'''
|<code><copy restore name='...' newname='...'/></code><br/>
|-
| '''Permission'''
|-
| '''Summary'''
|Creates Restores a copy of database with the database specified by {{Code|name}}. {{Code|newname}} must be a [[#Valid Names|valid database The name]]may include the timestamp of the backup file.
|-
| '''Errors'''
|The command fails if the target specified backup does not exist, if the database already existsto be restored is currently locked, or if it could not be restored for some other reason.|} ==INSPECT== {| width='100%'|-|width='130'|'''Syntax'''|{{Code|INSPECT}}|-| '''XML Syntax''' |<code><inspect/></code>|-| '''Permission'''|''READ''|-| '''Summary'''|Performs some integrity checks on the source opened database does not existand returns a brief summary.
|}
|-
| '''Summary'''
|Shows general information and meta data on the currently opened database.
|-
| '''Errors'''
|
* <code>XQUERY 1 to 10</code><br/>returns the sequence {{Code|(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)}}.
* <code>SET RUNS 10; </code> and <code>XQUERY 1 to 10</code><br/>returns the results after having run the query 10 times.* <code>SET XMLPLAN true; </code> and <code>XQUERY 1 to 10</code><br/>returns the result and prints the query plan as XML.
|}
|-
| '''Summary'''
| Deletes the specified package with name the specified {{Code|name}}, optionally . What is called "name" can also be the id (which is the name followed by a the version) or the directory of the package.
|-
| '''Errors'''
| The command fails if the package to be deleted participates in a dependencyis required by another package.
|}
|-
| '''Summary'''
|Replaces a document resources in the currently opened database, addressed by {{Code|path}}, with the file , directory or XML string specified by {{Code|input}}, or adds a new document documents if no resource exists at the resource does not exist yetspecified path.
|-
| '''Errors'''
|The command fails if no database is opened, or if the specified path points to a database directory, or if the input is not foundinvalid.
|-
| '''Examples'''
|-
| '''Summary'''
|Stores a [[Binary Data|raw file]] specified via {{Code|input}} in the opened database to the specified {{Code|path}}. {{Code|:* The input}} may either be a file reference, a remote URL, or a plain string. * If the path denotes a directory, it needs to be suffixed with a slash ({{Code|/}}).* An existing resource will be replaced.
|-
| '''Errors'''
|}
=Server AdministrationMonitoring=
==SHOW SESSIONS==
|-
| '''Summary'''
|Shows all users that are registered in visible to the databasecurrent user. If a {{Code|database}} is specified, all user only those users will be shown for which a pattern was specified that matches the database name.
|-
| '''Errors'''
| '''Errors'''
|The command fails if a user tried to kill his/her own session.
|}
==JOBS LIST==
{| width='100%'
|-
|width='130'|'''Syntax'''
|{{Code|JOBS LIST}}
|-
| '''XML Syntax'''
|<code><jobs-list/></code><br/>
|-
| '''Permission'''
|''ADMIN''
|-
| '''Summary'''
|Returns information on all jobs that are currently queued or executed. See {{Function|Jobs|jobs:list-details}} for more details on the returned table entries.
|}
==JOBS RESULT==
{| width='100%'
|-
|width='130'|'''Syntax'''
|{{Code|JOBS RESULT [id]}}
|-
| '''XML Syntax'''
|<code><jobs-result id='...'/></code><br/>
|-
| '''Permission'''
|''ADMIN''
|-
| '''Summary'''
|Returns the cached result of a query with the specified job id:
* Results can only be retrieved once. After retrieval, the cached result will be dropped.
* If the original query has raised an error, the cached error will be raised instead.
|-
| '''Errors'''
|The command fails if the addressed job is still running or if the result has already been retrieved.
|}
==JOBS STOP==
{| width='100%'
|-
|width='130'|'''Syntax'''
|{{Code|JOBS STOP [id]}}
|-
| '''XML Syntax'''
|<code><jobs-stop id='...'/></code><br/>
|-
| '''Permission'''
|''ADMIN''
|-
| '''Summary'''
|Cancels the execution of a job with the specified id, or drops the cached result of a query. Unknown ids are ignored. All jobs are gracefully stopped; it is up to the process to decide when it is safe to shut down.
|}
|-
| '''Summary'''
|Drops the user with the specified {{Code|name}}. The [[#Glob Syntax|Glob Syntax]] can be used to address more than one database or user. If a glob {{Code|pattern}} is specified, only the assigned database pattern will be removed.
|-
| '''Errors'''
|-
| '''Summary'''
|Evaluates the contents of {{Code|file}} as XQuery expression. If the file ends with the suffix {{Code|.bxs}}, the file content contents will be evaluated as [[#Basics|command script]]. This command can be used to run several commands in a single row, with no other transactionintervening the execution.
|-
| '''Errors'''
| '''Examples'''
|
* <code>RUN query.xq</code><br/>will evaluated evaluate the specified file as XQuery expression* <code>RUN commands.bxs</code><br/>will evaluated evaluate the specified file as command script
|}
|-
| '''Summary'''
|Evaluates the specified {{Code|input}} as [[#Basics|command script]]. This command can be used to run several commands in a single row, with no other transactionintervening the execution.
|-
| '''Errors'''
| '''Examples'''
|
|}
=Changelog=
;Version 9.3
* Added: {{Command|ALTER BACKUP}}
;Version 8.6
* Updated: {{Command|SHOW USERS}}: If called by non-admins, will only return the current user
;Version 8.5
* Added: {{Command|JOBS LIST}}, {{Command|JOBS RESULT}}, {{Command|JOBS STOP}}
* Updated: [[#Valid Names|Valid Names]]: allow dots (except as first and last character)
;Version 8.4
* Updated: {{Command|CREATE INDEX}}, {{Command|DROP INDEX}}, {{Command|INFO INDEX}}: token index added
* Updated: {{Command|INFO STORAGE}}: Query argument removed, start/end added to XML syntax.
* Updated: {{Command|INFO INDEX}}: Token index added; index {{Code|TAG}} renamed to {{Code|ELEMNAME}}; index {{Code|ATTNAME}} renamed to {{Code|ATTRNAME}}
* Updated: {{Command|OPTIMIZE}}: adopt original index options
;Version 8.2
* Removed: {{Code|CREATE EVENT}}, {{Code|DROP EVENT}} and {{Code|SHOW EVENTS}} command
;Version 8.0
* Updated: commands for [[#User Management|User Management]]
* Updated: {{Command|OPEN}}: path argument added
;Version 7.9
* Added: {{Command|TEST}} runs XQUnit tests.
;Version 7.7
* Updated: syntax of [[#Valid Names|valid names]].
;Version 7.5
* Added: {{Command|EXECUTE}} executes a command script.
* Added: {{Command|INSPECT}} performs integrity checks.
;Version 7.3
* Added: [[#XML Syntax|XML Syntax]] added.
* Updated: {{Command|CHECK}} can now be used to create empty databases.
;Version 7.2.1
* Updated: permissions for {{Command|GET}} and {{Command|SET}} changed from {{Code|READ}} to {{Code|NONE}}.
;Version 7.2
* Updated: {{Command|CREATE INDEX}}, {{Command|DROP INDEX}} ({{Code|PATH}} argument removed. Path summary is always available now and updated with {{Command|OPTIMIZE}}).
* Updated: permissions for {{Command|REPO DELETE}}, {{Command|REPO INSTALL}} and {{Command|REPO LIST}}.
;Version 7.1
* Updated: {{Command|KILL}} (killing sessions by specifying IP:port)
;Version 7.0
* Added: {{Command|FLUSH}}, {{Command|RETRIEVE}}, {{Command|STORE}}.
* Updated: {{Command|ADD}}: simplified arguments.
