Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
Multiple commands can be written in a single line and separated by semicolons, or stored as command script. Lines starting with <code>#</code> are interpreted as comments and are skipped. The With the following script creates , a databaseis created, adds two documents are added to it , and performs a queryis performed:
ADD input.xml
This is why database commands can also be specified in The XMLsyntax 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:
<add>input.xml</add>
* <code>.</code>: hidden folders (e.g. the [[Logging|.logs directory]])
{{Mark|Updated with Version 8.4:}} Token index added.
{{Mark|Updated with Version 8.4:}} Token index added.
{{Mark|Updated with Version 8.4}}: Query argument removed, start/end added to XML syntax.
→SHOW USERS
This article is part of the [[Getting Started]] Section.
It lists all database commands supported by BaseX.
Commands can e.g. be executed from the [[Command-Line Options#BaseX_Standalone|Command Line]],as part of [[#Command Scripts|Scripts]], via the [[Clients]], [[REST]], the input field in the [[GUI]], and other ways. If the GUI is used, all commands that are triggered by the GUI itselfwill show up in the [[GUI#Visualizations|Info View]].The [[User_Management|Permission]] fields indicate whichrights are required by a user to perform a command in the client/server architecture.
=Basics=
==Command Scripts==
On command line, multiple commands can be written down in a single line (separated by semicolons). You can also put them into a command script: Database commands in both the string and XML syntax can be placed in a text file and stored on disk. The extension for as file with the BaseX command scripts is 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 automatically be recognized and evaluated as such.
===String Syntax===
<pre class="brush:xml">
CREATE DB test
ADD TO embedded.xml <root>embedded</root>
# run query
XQUERY <hits>{ count(//text())}</hits>CLOSE
</pre>
===XML Syntax===
The string syntax is limited when XML snippets need to be embedded in a command,or when complex queries are to be specified.
<pre class="brush:xml">
<commands>
<create-db name='test'/>
<add path='embedded.xml'><root>embedded</root></add>
<!-- run query --> <xquery><![CDATA[ <hits>{ count(//text())}</hits> ]]></xquery> <close/>
</commands>
</pre>
* <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]]
|-
| '''Summary'''
|This convenience command combines [[#OPEN{{Command|OPEN]] }} and [[#CREATE DB{{Command|CREATE DB]]}}: if a database with the name {{Code|input}} exists, it is opened. Otherwise, a new database is created; if the specified input points to an existing resource, it is stored as initial content.
|-
| '''Errors'''
|-
| '''Summary'''
|Exports all documents in the database to the specified file {{Code|path}}, using the serializer options specified by the <code>[[Options#EXPORTER{{Option|EXPORTER]]</code> }} option.
|-
| '''Errors'''
|-
| '''Summary'''
|Creates the specified [[Indexes#Value Indexes|Value Index]]. The current [[Options#Indexing|Index Options]] will be considered when creating the index.
|-
| '''Errors'''
==DROP INDEX==
{| width='100%'
|-
| '''Summary'''
|Shows general information and meta data on the currently opened database.
|-
| '''Errors'''
==INFO INDEX==
{| width='100%'
|-
|width='130'|'''Syntax'''
|{{Code|INFO INDEX ([TAGELEMNAME|ATTNAMEATTRNAME|PATH|TEXT|ATTRIBUTE|TOKEN|FULLTEXT])}}
|-
| '''XML Syntax'''
|<code><info-index type='tagelemname|attnameattrname|path|text|attribute|token|fulltext'/></code><br/>
|-
| '''Permission'''
==INFO STORAGE==
{| width='100%'
|-
| '''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.
|}
|Adds a file, directory or XML string specified by {{Code|input}} to the currently opened database at the specified {{Code|path}}:
* {{Code|input}} may either be a single XML document, a directory, a remote URL or a plain XML string.
* A document with the same path may occur than once in a database. If this is unwanted, [[#REPLACEthe {{Command|REPLACE]] }} command can be used.* If a file is too large to be added in one go, its data structures will be cached to disk first. Caching can be enforced by turning the [[Options#ADDCACHE{{Option|ADDCACHE]] }} option on.If files are to be added to an empty database, it is usually faster to use the [[#CREATE DB{{Command|CREATE DB]] }} command and specify the initial input as argument.
|-
| '''Errors'''
|-
| '''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'''
|-
| '''Summary'''
|Optimizes the index structures, meta data and statistics of the currently opened database. :* If the {{Code|ALL}} flag is specified, the internal all database structures are completely rebuilt; this often leads reconstructed. The database size will be reduced, and all orphaned data will be deleted.* Without {{Code|ALL}}, only the outdated index structures and database statistics will be updated. If the database is completely up-to a reduction of -date, nothing will be done.* Database options will be adopted from the total original database size. Only {{Option|AUTOOPTIMIZE}} and (if {{Code|ALL}} is specified) {{Option|UPDINDEX}} will be adopted from the current options.
|-
| '''Errors'''
|-
| '''Summary'''
|Explicitly flushes the buffers of the currently opened database to disk. This command is applied if [[Options#AUTOFLUSH{{Option|AUTOFLUSH]] }} has been set to {{Code|false}}.
|-
| '''Errors'''
|}
=Server AdministrationMonitoring=
==SHOW SESSIONS==
==SHOW USERS==
{{Mark|Updated with Version 8.6}}: If called by non-admins, will only return the current user
{| width='100%'
|-
| '''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.
|}
==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'''
|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'''
|-
| '''Summary'''
|Exits the console mode (alias of [[#EXIT{{Command|EXIT]]}}).
|}
=Changelog=
;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: <code>[[#CREATE INDEX{{Command|CREATE INDEX]]</code>}}, <code>[[#DROP INDEX{{Command|DROP INDEX]]</code>}}, <code>[[#INFO INDEX{{Command|INFO INDEX]]</code>}}: token index added* Updated: <code>[[#INFO STORAGE{{Command|INFO STORAGE]]</code>}}: 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: <code>[[#OPEN{{Command|OPEN]]</code>}}: path argument added
* Removed: {{Code|CS}} command
* Added: <code>[[#QUIT{{Command|QUIT]]</code>}}
;Version 7.9
* Added: <code>[[#TEST{{Command|TEST]]</code> }} runs XQUnit tests.
;Version 7.7
* Updated: syntax of [[#Valid Names|valid names]].
;Version 7.5
* Added: <code>[[#EXECUTE{{Command|EXECUTE]]</code> }} executes a command script.* Added: <code>[[#INSPECT{{Command|INSPECT]]</code> }} performs integrity checks.
* Added: automatic detection of [[#Basics|Command Scripts]].
* Removed: {{Code|SHOW DATABASES}}; information is also returned by <code>[[#SHOW SESSIONS{{Command|SHOW SESSIONS]]</code>}}.* Removed: <code>[[#OPEN{{Command|OPEN]]</code>}}: path argument.
;Version 7.3
* Added: [[#XML Syntax|XML Syntax]] added.
* Updated: <code>[[#CHECK{{Command|CHECK]]</code> }} can now be used to create empty databases.* Updated: Names and paths in <code>[[#OPEN{{Command|OPEN]]</code> }} and <code>[[#LIST{{Command|LIST]]</code> }} are now specified as separate arguments.
;Version 7.2.1
* Updated: permissions for <code>[[#GET{{Command|GET]]</code> }} and <code>[[#SET{{Command|SET]]</code> }} changed from {{Code|READ}} to {{Code|NONE}}.
;Version 7.2
* Updated: <code>[[#CREATE INDEX{{Command|CREATE INDEX]]</code>}}, <code>[[#DROP INDEX{{Command|DROP INDEX]]</code> }} ({{Code|PATH}} argument removed. Path summary is always available now and updated with [[#OPTIMIZE{{Command|OPTIMIZE]]}}).* Updated: permissions for <code>[[#REPO DELETE{{Command|REPO DELETE]]</code>}}, <code>[[#REPO INSTALL{{Command|REPO INSTALL]]</code> }} and <code>[[#REPO LIST{{Command|REPO LIST]]</code>}}.
;Version 7.1
* Updated: <code>[[#KILL{{Command|KILL]]</code> }} (killing sessions by specifying IP:port)
;Version 7.0
* Added: <code>[[#FLUSH{{Command|FLUSH]]</code>}}, <code>[[#RETRIEVE{{Command|RETRIEVE]]</code>}}, <code>[[#STORE{{Command|STORE]]</code>}}.* Updated: <code>[[#ADD{{Command|ADD]]</code>}}: simplified arguments.
