== arcadedb
{{arcadedb}} is a CHICKEN Scheme egg module providing a driver or REPL
for the [[https://arcadedb.com|'''ArcadeDB''']] database.
[[toc:]]
== About '''ArcadeDB'''
'''ArcadeDB''' is a multi-model NoSQL database providing the models:
* Key-Value,
* Document,
* Graph,
while supporting a wide range of data query languages, such as:
* [[https://docs.arcadedb.com/#_sql|SQL]] (dialect),
* [[https://opencypher.org/resources/|Cypher]],
* [[https://tinkerpop.apache.org/docs/current/|Gremlin]],
* [[https://graphql.org/|GraphQL]],
* [[https://www.mongodb.com/docs/manual/|MQL]] (Mongo)
as well as providing a JSON/REST/HTTP API.
=== SQL
The native query language of '''ArcadeDB''' is a dialect of SQL, closely related to
''OrientDB'''s OSQL, which supports the [[https://www.geeksforgeeks.org/sql-ddl-dql-dml-dcl-tcl-commands/|SQL command categories]]:
* '''DDL''' - Data Definition Language, via {{CREATE}}, {{DROP}}, {{ALTER}}, {{TRUNCATE}} of {{TYPE}}s
* '''DQL''' - Data Query Language, via {{SELECT}}, {{TRAVERSE}}, {{MATCH}}
* '''DML''' - Data Manipulation Language, via {{INSERT}}, {{UPDATE}}, {{DROP}}, {{EXPLAIN}}, {{PROFILE}}
for the remaining categories holds:
* '''DCL''' - Data Control Language, does not apply due to only [[https://docs.arcadedb.com/#Security|server level users]]
* '''TCL''' - Transaction Control Language, via [[https://docs.arcadedb.com/#HTTP-API|HTTP REST endpoints]]
== About {{arcadedb}}
The {{arcadedb}} module implements a driver and console for '''ArcadeDB''' in
''CHICKEN Scheme'' with the functionality:
* [[#server-connection|Server Connection]]
* [[#server-information|Server Information]]
* [[#server-databases|Server Databases]]
* [[#database-management|Database Management]]
* [[#databse-connection|Database Connection]]
* [[#database-interaction|Database Interaction]]
* [[#database-macros|Database Macros]]
=== Runtime Dependencies
Naturally, {{arcadedb}} requires a running remote or local '''ArcadeDB''' server:
* [[https://github.com/ArcadeData/arcadedb/releases/latest|ArcadeDB]]
which in turn requires a ''Java'' distribution, i.e. ''OpenJDK'', in versions 11 up to 15.
A local server setup is described below.
Furthermore, the {{arcadedb}} module requires {{curl}} for the HTTP requests:
* [[http://curl.se|curl]]
during runtime, and imports the {{uri-common}} egg to url-encode strings,
as well as the {{medea}} egg to decode JSON:
* [[https://wiki.call-cc.org/eggref/5/uri-common|uri-common]]
* [[https://wiki.call-cc.org/eggref/5/medea|medea]]
== Local Server Setup
A local '''ArcadeDB''' server can be set up via [[#install|install]] or [[#container|container]].
=== Install
*# Download package: [[https://github.com/ArcadeData/arcadedb/releases/latest|'''ArcadeDB''' package]]
*# Extract package: {{tar -xf arcadedb-latest.tar.gz}}
*# Start server: {{ARCADEDB_HOME=/path/to/arcadedb/ bin/server.sh -Darcadedb.server.rootPassword=mypassword &}}
*# Exit server: {{kill `cat bin/arcade.pid`}}
=== Container
*# Install [[https://www.docker.com/|Docker]]
*# Download container: {{docker pull arcadedata/arcadedb}}
*# Start container: {{docker run --rm -d -p 2480:2480 -e JAVA_OPTS="-Darcadedb.server.rootPassword=mypassword --name arcadedb0 arcadedata/arcadedb}}
*# Stop container: {{docker stop arcadedb0}}
== Procedures
=== Help Message
==== a-help
(a-help)
Returns '''void''', prints help about using the {{arcadedb}} module.
=== Server Connection
==== a-connect
(a-connect user pass host . port)
Returns '''alist''' with single entry if connection to server using '''string'''s
{{user}}, {{pass}}, {{host}}, and optionally '''number''' {{port}}, succeded;
returns {{#f}} if a server error occurs or no response is received.
=== Server Information
==== a-ready?
(a-ready?)
Returns '''boolean''' answering if server is ready.
==== a-version
(a-version)
Returns '''string''' version number of the server;
returns {{#f}} if a server error occurs or no response is received.
=== Server Databases
==== a-list
(a-list)
Returns '''list''' of '''symbol'''s holding available databases of the server;
returns {{#f}} if a server error occurs or no response is received.
==== a-exist?
(a-exist? db)
Returns '''boolean''' answering if database '''symbol''' {{db}} exists on the server.
=== Database Management
==== a-new
(a-new db)
Returns '''boolean''' that is true if creating new database '''symbol''' {{db}} succeded;
returns {{#f}} if a server error occurs or no response is received.
==== a-delete
(a-delete db)
Returns '''boolean''' that is true if deleting database '''symbol''' {{db}} osucceded;
returns {{#f}} if a server error occurs or no response is received.
=== Database Connection
==== a-use
(a-use db)
Returns '''boolean''' that is true if database '''symbol''' {{db}} is connected;
returns {{#f}} if a server error occurs or no response is received.
==== a-using
(a-using)
Returns '''symbol''' naming current database;
returns {{#f}} if no database is connected.
=== Database Interaction
==== a-query
(a-query db lang query)
Returns '''list''' holding the result of '''string''' {{query}} in language '''symbol''' {{lang`}} on current database;
returns {{#f}} if a server error occurs or no response is received.
==== a-command
(a-command db lang cmd)
Returns '''list''' holding the result of '''string''' {{cmd}} in language '''symbol''' {{lang}} to current database;
returns {{#f}} if a server error occurs or no response is received.
=== Database Macros
==== a-schema
(a-schema)
Returns '''alist''' of type descriptions for current database;
returns {{#f}} if a server error occurs or no response is received.
This function emulates the SQL {{DESCRIBE}} statement.
==== a-script
(a-script path)
Returns '''list''' holding the result of the last statement of SQL script in '''string''' {{path}} executed on current database;
returns {{#f}} if a server error occurs or no response is received.
A SQL script file has to have the file extension {{.sql}}.
==== a-upload
(a-upload path type)
Returns '''boolean''' that is true if uploading ''JSON'' file at '''string''' {{path}}
into current database as '''symbol''' {{type}} succeded;
returns {{#f}} if a server error occurs or no response is received.
A JSON script file has to have the file extension {{.json}}.
==== a-backup
(a-backup)
Returns '''boolean''' that is true if backing-up current database succeded.
==== a-extract
(a-extract url)
'''boolean''' that is true if importing from '''string''' {{url}} into current database succeded;
returns {{#f}} if a server error occurs or no response is received.
This function can be a minimalistic ETL (Extract-Transform-Load) tool:
If one needs to import data from another database with a HTTP API
and the query can be encoded ([[https://docs.arcadedb.com/#HTTP-API|as for '''ArcadeDB''']]) in the URL,
the extraction and transformation is performed in the remote query,
while the loading corresponds to the import of the query result.
The supported formats are [[https://docs.arcadedb.com/#Importer|OrientDB, Neo4J, GraphML, GraphSON, XML, CSV, JSON, RDF]].
==== a-stats
(a-stats)
Returns '''list'''-of-'''alist'''s reporting statistics on current database;
returns {{#f}} if a server error occurs or no response is received.
==== a-health
(a-health)
Returns '''list'''-of-'''alist'''s reporting health of current database;
returns {{#f}} if a server error occurs or no response is received.
==== a-repair
(a-repair)
Returns '''boolean''' that is true if automatic repair succeeded.
==== a-comment
(a-comment)
(a-comment msg)
Returns '''string''' current database comment of current database, if {{msg}} is not passed;
returns {{#t}} if '''string''' {{msg}} was set as comment for current database succeded;
returns {{#f}} if no comment is set, a server error occurs or no response is received.
This function emulates the SQL {{COMMENT ON DATABASE}} statement,
by creating a type {{D}} and upserting or reading the first {{comment}} property.
== Changelog
* {{0.1}} [[https://github.com/gramian/chicken-arcadedb|Initial Release]] (2022-11-15)
* {{0.2}} [[https://github.com/gramian/chicken-arcadedb|Minor Update]] (2022-11-16)
* {{0.3}} [[https://github.com/gramian/chicken-arcadedb|Minor Update]] (2022-??-??)
== License
Copyright (c) 2022 ''Christian Himpe'' under [[https://spdx.org/licenses/zlib-acknowledgement.html|zlib-acknowledgement]] license.