ARLAS CLI Documentation

README.md

@@ -1,5 +1,9 @@
 # arlas_cli
 
-ARLAS Command Line is for managing collections, indices and ARLAS configurations.
+__ARLAS Command Line__ (`arlas_cli`) is for managing the ARLAS data and configurations.
 
 See the documentation at https://gisaia.github.io/arlas_cli/
+
+## Developer section
+
+To run the commands locally from the project root, simply replace `arlas_cli` by `python3.10 -m arlas.cli.cli`

arlas/cli/configurations.py

@@ -78,7 +78,7 @@ def create_configuration(
 
 @configurations.command(help="Add a configuration for ARLAS Cloud", name="login")
 def login(
-    auth_login: str = typer.Argument(help="login"),
+    auth_login: str = typer.Argument(help="ARLAS login"),
     elastic_login: str = typer.Argument(help="Elasticsearch login"),
     elastic: str = typer.Argument(help="Elasticsearch url"),
     auth_org: str = typer.Option(default=None, help="ARLAS IAM Organization, default is your email domain name"),

docs/docs/collections.md.template

@@ -0,0 +1,250 @@
+## ARLAS Collections
+
+ARLAS collections are built on top of [elasticsearch (ES) index](concepts.md#es-index). They describe the basic data structure for its visualization and elements needed for the data access policy.
+
+`arlas_cli` provide tools to manage the ARLAS collections with the `collections` command.
+
+**List collections management commands**
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --help
+```
+
+## create
+
+An ARLAS Collection is linked to an index or even an index pattern.
+
+The command line options let you specify how the index should be used by the collection.
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --config local create --help
+```
+
+!!! note "Collection visibility"
+
+    The visibility options (`--public`, `--private`, `--owner` and `--orgs`)  allow you to choose who can access the collection.
+
+!!! note "--owner"
+
+    If ARLAS is used with ARLAS IAM (for example with ARLAS Cloud), then a collection must be associated to an organisation.
+
+    Example:
+
+    `--owner your.organisation.com`
+
+    By default, the organisation referenced in your `config` is used as owner.
+
+
+### Create an ARLAS collection
+
+The collection has to reference an available ES index or index pattern with the [arlas_cli configuration](confs.md#configurations).
+
+The index option sets the targeted index:`--index index_name`
+
+!!! tip "Index pattern"
+
+    The collection can target an index pattern.
+    Instead of an index name, the target is an expression using `*` to reference multiple ES indices.
+
+    Example:
+
+    `--index index_name_prefix*`
+
+    All the indices have to share exactly the same data mapping.
+
+    The data contained in all referenced indices are then explorable together in ARLAS.
+
+
+The collection also describe a basic structure for spatio-temporel datasets:
+
+- **ID path**: A data field containing unique element identifier. `--id-path unique_id_field`
+- **Centroid path**: A data field containing a point geometry used for aggregations `--centroid-path point_geom_field`
+- **Geometry path**: A data field containing a geometry representing the element `--geometry-path element_geom_field`
+- **Date path**: A data field containing the date associated to each element `--date-path date_field`
+
+!!! tip "Pretty name"
+
+    A pretty name for the collection can be set at the creation with the `display-name` option
+
+    Example:
+
+    `--display-name "Pretty Collection Name"`
+
+
+To create the collection, run the following command:
+
+<!-- termynal -->
+```shell
+> arlas_cli  collections \
+   --config {local} \
+   create {collection_name} \
+   --index {index_name} \
+   --id-path {unique_id_field} \
+   --centroid-path {point_geom_field} \
+   --geometry-path {element_geom_field} \
+   --date-path {date_field} \
+   --display-name {"Pretty Collection Name"}
+```
+
+## name
+
+The collection can be defined by a pretty name. It can be set with `name` subcommand:
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --config local name --help
+```
+
+### Set a pretty name for the collection
+
+The pretty name can be used in ARLAS to display the collection. It can also be set by the `--display-name` option at the [collection creation](#create).
+
+To set it with the `name` subcommand:
+```shell
+> arlas_cli collections \
+   --config {local} \
+   name {collection_name} {"Pretty Collection Name"}
+```
+
+## set_alias
+
+The data fields are sometimes not very suitable in ARLAS Exploration dashboards. You can set aliases to improve their display in the interface.
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --config local set_alias --help
+```
+### Set a pretty name for a data field
+
+Each field of the data has a raw name. It can be replaced by a pretty name to display. For example:
+```shell
+> arlas_cli collections \
+   --config {local} \
+   set_alias {collection_name} \
+   {raw_field_name} {"Pretty Field Name (unit)"}
+```
+
+## list
+
+### List available collections
+
+You can access the list of available collections with the `list` subcommand:
+
+<!-- termynal -->
+```shell
+> arlas_cli collections --config local set_alias --help
+
+Usage: arlas_cli collections list [OPTIONS]
+
+  List collections
+
+Options:
+  --help  Show this message and exit.
+
+```
+
+
+## describe
+
+### Describe a collection
+
+The `describe` command line provides a description of the collection's structure (fields) and its metadata.
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --config local describe --help
+```
+
+## count
+
+### Count the number of element within a collection
+
+The `count` command show the total number of elements (data rows) accessible in a collection.
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --config local count --help
+```
+
+## sample
+
+### Display a sample of the collection data
+
+The `sample` command show few data rows accessible in a collection.
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --config local sample --help
+```
+
+!!! note
+    The number of rows to display can be set with `--size` option
+
+## private
+
+By default, a collection is private, it can only be seen by the members of the owner or shared organisation.
+
+In that case, an ARLAS user has to be logged and have the correct authorisations.
+
+### Set the collection as private
+
+To switch a collection from **public** to **private**, use the `private` command:
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --config local private --help
+```
+
+## public
+
+A public collection can be accessed in ARLAS dashboards without being logged. It can be used to host demo dashboards for example.
+
+### Set the collection as public
+
+To switch a collection from **private** to **public**, use the `public` command:
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --config local public --help
+```
+
+## share
+
+A collection can be shared between different organisations to make it available for its users.
+
+### Share collections between organisations
+
+A collection can be shared to other organisation with the `share` command:
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --config local share --help
+```
+
+## unshare
+
+The right to access a collection can be removed to the users of an organisation.
+
+###  Remove collection access for an organisation
+
+The access to a collection can be removed with the `unshare` command:
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --config local unshare --help
+```
+
+## delete
+
+A collection can be deleted. It doesn't delete the data (ES index can still exist) but it will no longer be accessible in ARLAS.
+
+### Delete a collection
+
+The collection can be removed with the `delete` command:
+
+<!-- termynal -->
+```shell
+> !!!execute arlas_cli collections --config local delete --help
+```