Datasets, Groups and users ========================== Specklia is divided up into Datasets, Groups and Users. This section explains what each of these things are, and how they interact. User IDs -------- Each user has a unique ID, which can be obtained from the client using the `Specklia.user_id `_ property. This user ID is the correct way to uniquely identify yourself to other Specklia users, or to Earthwave. It's a little clunkier than a name or an email, but it has the advantage that Earthwave cannot uniquely identify users and profit from selling their data to third parties. See our `privacy policy `_ for further details. Datasets -------- Data is stored within Specklia in datasets. Each dataset is a large collection of points with pre-defined fields. You can list all of the datasets that you currently have the ability to query using `Specklia.list_datasets() `_. The ``geometry`` and ``timestamp`` fields are mandatory. Other custom fields can be defined when the dataset is created. Datasets must first be created, and then have data added to them (i.e. uploaded / ingested). Datasets are created using `Specklia.create_dataset() `_. Once a dataset has been created, points can be added to it using `Specklia.add_points_to_dataset() `_. To delete a dataset from Specklia, using `Specklia.delete_dataset() `_. Individual sources can be deleted from a dataset by calling the DELETE ``/source`` endpoint with the appropriate ``source_id`` and ``dataset_id``. You must have READ_WRITE or ADMIN permissions within the group that owns the dataset to delete sources. When a source is deleted, all its data rows are removed, and the dataset's metadata (coverage, timestamps, and custom column statistics) is automatically recalculated. It is not currently possible to update or delete specific individual points within a dataset. We will be adding these capabilities soon. Datasets can be queried using `Specklia.query_dataset() `_. Note that querying a large area / duration is likely to take a long time, and may fail due to various timeouts built into Specklia. Groups ------ Specklia is divided up into Groups. Groups are intended to allow users to share data amongst themselves. Each group has a name, contains one or more users, and contains one or more datasets. A specklia user can list all of the groups they are currently a member of using `Specklia.list_groups() `_ There are two special kinds of groups. Firstly, every user is a member of a group named after their user ID. This is their "personal group". Every dataset that a user uploads to Specklia starts off in their personal group, and must be moved into other groups from there. Secondly, every user is a member of a special group called ``all_users``. Datasets within the ``all_users`` group are therefore accessible by all Specklia users. Beyond personal groups and the ``all_users`` group, Specklia users are free to create, manipulate and destroy groups as they see fit. Groups are created using `Specklia.create_group() `_, renamed using `Specklia.change_group_name() `_ and deleted using `Specklia.delete_group() `_. Once a group exists, datasets can be added and removed using `Specklia.update_dataset_ownership() `_. Note that all datasets belong to exactly one group at all times. Users can be added to and removed from a group using `Specklia.add_user_to_group() `_ and `Specklia.delete_user_from_group() `_. Permissions within Groups ------------------------- Specklia features permissions management in order to allow individuals to upload and distribute private datasets. There are three levels of permissions: ``READ_ONLY``, ``READ_WRITE`` and ``ADMIN``. Permissions are implemented at the level of users and groups. For example, a notional user 'Charlie' will have by default: * ``ADMIN`` permissions within Charlie's personal group. * ``READ_ONLY`` permissions within the ``all_users`` group. If Charlie is invited to a different Specklia group, Charlie will start off in that group with ``READ_ONLY`` permissions. Anyone who has ``ADMIN`` permissions within that group can then change Charlie's permissions. * Users with ``READ_ONLY`` permissions in a group are able to query datasets within that group, but do nothing more. * Users with ``READ_WRITE`` permissions in a group can add data to and delete data from datasets within that group. They are not able to add whole datasets to the group, or remove them from the group. * Users with ``ADMIN`` permissions in a group are able to do anything to any dataset within that group, including adding and removing datasets and users. Once a user has been added to a group using `Specklia.add_user_to_group() `_, their permissions can be set by any of the group's admins using `Specklia.set_user_privileges() `_. The group's admins can use `Specklia.list_users() `_ to list all of the users within a group, along with their permissions.