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/