Skip to content

collections

ARLAS Collections

ARLAS collections are built on top of elasticsearch (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

arlas_cli collections --help
Usage: arlas_cli collections [OPTIONS] COMMAND [ARGS]...

╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --config TEXT Name of the ARLAS configuration to use from your │
│ configuration file │
│ (/Users/gaudan/.arlas/cli/configuration.yaml). │
│ [default: None] │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────╮
│ count Count the number of hits within a collection (or all collection │
│ if not provided) │
│ create Create a collection │
│ delete Delete a collection │
│ describe Describe a collection │
│ list List collections │
│ name Set the collection display name │
│ private Set collection visibility to private │
│ public Set collection visibility to public │
│ sample Display a sample of a collection │
│ set_alias Set the field display name │
│ share Share the collection with the organisation │
│ unshare Unshare the collection with the organisation │
╰────────────────────────────────────────────────────────────────────────────╯

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.

arlas_cli collections --config local create --help
Usage: arlas_cli collections create [OPTIONS] COLLECTION

Create a collection

╭─ Arguments ────────────────────────────────────────────────────────────────╮
│ * collection TEXT Collection's name [default: None] [required] │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --model TEXT Name of the model within your │
│ configuration, or URL or file path │
│ [default: None] │
│ --index TEXT Name of the index referenced by │
│ the collection │
│ [default: None] │
│ --display-name TEXT Display name of the collection │
│ [default: None] │
│ --public --no-public Whether the collection is public │
│ or not │
│ [default: no-public] │
│ --owner TEXT Organisation's owner │
│ [default: None] │
│ --orgs TEXT List of organisations accessing │
│ the collection │
│ --id-path TEXT Override the JSON path to the id │
│ field. │
│ [default: None] │
│ --centroid-path TEXT Override the JSON path to the │
│ centroid field. │
│ [default: None] │
│ --geometry-path TEXT Override the JSON path to the │
│ geometry field. │
│ [default: None] │
│ --date-path TEXT Override the JSON path to the date │
│ field. │
│ [default: None] │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯

See full arlas_cli documentation at https://gisaia.github.io/arlas_cli/


Collection visibility

The visibility options (--public, --private, --owner and --orgs) allow you to choose who can access the collection.

--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.

The index option sets the targeted index:--index index_name

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

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:

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:

arlas_cli collections --config local name --help
Usage: arlas_cli collections name [OPTIONS] COLLECTION NAME

Set the collection display name

╭─ Arguments ────────────────────────────────────────────────────────────────╮
│ * collection TEXT Collection's name [default: None] [required] │
│ * name TEXT The display name [default: None] [required] │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯

See full arlas_cli documentation at https://gisaia.github.io/arlas_cli/


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.

To set it with the name subcommand: 

> 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.

arlas_cli collections --config local set_alias --help
Usage: arlas_cli collections set_alias [OPTIONS] COLLECTION FIELD_PATH
[DISPLAY_NAME]

Set the field display name

╭─ Arguments ────────────────────────────────────────────────────────────────╮
│ * collection TEXT Collection's name [default: None] │
│ [required] │
│ * field_path TEXT The field path [default: None] │
│ [required] │
│ display_name [DISPLAY_NAME] The field's display name. If none │
│ provided, then the alias is removed │
│ if it existed │
│ [default: None] │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯

See full arlas_cli documentation at https://gisaia.github.io/arlas_cli/


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: 

> 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:

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.

arlas_cli collections --config local describe --help
Usage: arlas_cli collections describe [OPTIONS] COLLECTION

Describe a collection

╭─ Arguments ────────────────────────────────────────────────────────────────╮
│ * collection TEXT Collection's name [default: None] [required] │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯

See full arlas_cli documentation at https://gisaia.github.io/arlas_cli/


count

Count the number of element within a collection

The count command show the total number of elements (data rows) accessible in a collection.

arlas_cli collections --config local count --help
Usage: arlas_cli collections count [OPTIONS] [COLLECTION]

Count the number of hits within a collection (or all collection if not
provided)

╭─ Arguments ────────────────────────────────────────────────────────────────╮
│ collection [COLLECTION] Collection's name [default: None] │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯

See full arlas_cli documentation at https://gisaia.github.io/arlas_cli/


sample

Display a sample of the collection data

The sample command show few data rows accessible in a collection.

arlas_cli collections --config local sample --help
Usage: arlas_cli collections sample [OPTIONS] COLLECTION

Display a sample of a collection

╭─ Arguments ────────────────────────────────────────────────────────────────╮
│ * collection TEXT Collection's name [default: None] [required] │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --pretty --no-pretty [default: pretty] │
│ --size INTEGER [default: 10] │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯

See full arlas_cli documentation at https://gisaia.github.io/arlas_cli/


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:

arlas_cli collections --config local private --help
Usage: arlas_cli collections private [OPTIONS] COLLECTION

Set collection visibility to private

╭─ Arguments ────────────────────────────────────────────────────────────────╮
│ * collection TEXT Collection's name [default: None] [required] │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯

See full arlas_cli documentation at https://gisaia.github.io/arlas_cli/


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:

arlas_cli collections --config local public --help
Usage: arlas_cli collections public [OPTIONS] COLLECTION

Set collection visibility to public

╭─ Arguments ────────────────────────────────────────────────────────────────╮
│ * collection TEXT Collection's name [default: None] [required] │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯

See full arlas_cli documentation at https://gisaia.github.io/arlas_cli/


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:

arlas_cli collections --config local share --help
Usage: arlas_cli collections share [OPTIONS] COLLECTION ORGANISATION

Share the collection with the organisation

╭─ Arguments ────────────────────────────────────────────────────────────────╮
│ * collection TEXT Collection's name [default: None] [required] │
│ * organisation TEXT Organisation's name [default: None] │
│ [required] │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯

See full arlas_cli documentation at https://gisaia.github.io/arlas_cli/


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:

arlas_cli collections --config local unshare --help
Usage: arlas_cli collections unshare [OPTIONS] COLLECTION ORGANISATION

Unshare the collection with the organisation

╭─ Arguments ────────────────────────────────────────────────────────────────╮
│ * collection TEXT Collection's name [default: None] [required] │
│ * organisation TEXT Organisation's name [default: None] │
│ [required] │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯

See full arlas_cli documentation at https://gisaia.github.io/arlas_cli/


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:

arlas_cli collections --config local delete --help
Usage: arlas_cli collections delete [OPTIONS] COLLECTION

Delete a collection

╭─ Arguments ────────────────────────────────────────────────────────────────╮
│ * collection TEXT collection's name [default: None] [required] │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────╯

See full arlas_cli documentation at https://gisaia.github.io/arlas_cli/