FIWARE Short Time Historic (STH) - Comet

https://fiware-sth-comet.readthedocs.io/en/latest
Admin
FIWARE Short Time Historic (STH), also known as Comet, is a component of the FIWARE ecosystem...
Tokens:19,727
Snippets:72
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start STH Server with Custom Configuration

Source: https://fiware-sth-comet.readthedocs.io/en/latest/running

Demonstrates how to start the STH server with environment variables to specify the listening port, MongoDB connection URI, and whether to filter out empty results. This example uses a shell script execution.

```bash
STH_PORT=7777 DB_URI=mymongo.com:27777 FILTER_OUT_EMPTY=false ./bin/sth
```

--------------------------------

### STH-Comet Server Startup and Configuration (Bash)

Source: https://context7.com/context7/fiware-sth-comet_readthedocs_io_en/llms.txt

These examples demonstrate various ways to start the STH-Comet server using environment variables to configure port, database connection, authentication, data model, truncation, filtering, CORS, and logging.

```bash
# Basic startup with default configuration
./bin/sth
```

```bash
# Startup with custom port and MongoDB connection
STH_PORT=7777 DB_URI=mongodb.example.com:27017 ./bin/sth
```

```bash
# Connect to MongoDB replica set
DB_URI=10.0.1.1:27017,10.0.1.2:27017,10.0.1.3:27017 \
REPLICA_SET=rs0 \
./bin/sth
```

```bash
# Advanced configuration with authentication and data model
DB_USERNAME=sth_user \
DB_PASSWORD=secure_password \
DB_URI=mongodb.example.com:27017 \
DB_AUTH_SOURCE=admin \
DATA_MODEL=collection-per-entity \
SHOULD_STORE=both \
MAX_PAGE_SIZE=100 \
LOGOPS_LEVEL=INFO \
./bin/sth
```

```bash
# Configuration with time-based data truncation (30 days)
TRUNCATION_EXPIRE_AFTER_SECONDS=2592000 \
STH_PORT=8666 \
DB_URI=localhost:27017 \
./bin/sth
```

```bash
# Configuration with size-based truncation for raw data (1GB max)
TRUNCATION_SIZE=1073741824 \
TRUNCATION_MAX=10000 \
./bin/sth
```

```bash
# Configuration with filtering and custom settings
FILTER_OUT_EMPTY=true \
IGNORE_BLANK_SPACES=true \
DEFAULT_SERVICE=smartcity \
DEFAULT_SERVICE_PATH=/sensors \
DB_PREFIX=sth_ \
COLLECTION_PREFIX=sth_ \
POOL_SIZE=10 \
WRITE_CONCERN=1 \
./bin/sth
```

```bash
# Enable CORS for cross-origin requests
CORS_ENABLED=true \
STH_PORT=8666 \
./bin/sth
```

```bash
# Logging configuration
LOGOPS_LEVEL=DEBUG \
LOGOPS_FORMAT=json \
PROOF_OF_LIFE_INTERVAL=60 \
PROCESSED_REQUEST_LOG_STATISTICS_INTERVAL=60 \
./bin/sth
```

--------------------------------

### Clone GitHub Repository and Install Dependencies (Bash)

Source: https://fiware-sth-comet.readthedocs.io/en/latest/installation

This snippet demonstrates how to clone the fiware-sth-comet repository from GitHub and install its Node.js dependencies using npm. This is the first step for manual installation.

```bash
git clone https://github.com/telefonicaid/fiware-sth-comet.git
cd fiware-sth-comet/
npm install

```

--------------------------------

### STH Database Model Tool Options Explained

Source: https://fiware-sth-comet.readthedocs.io/en/latest/data-migration

Detailed explanation of the options for the sthDatabaseModelTool, including flags for analysis, migration, verbosity, collection removal/update, and database/collection targeting.

```bash
Usage: sthDatabaseModelTool [options]

  Options:

    -h, --help                         output usage information
    -V, --version                      output the version number
    -a, --analysis                     prints the results of the data model analysis including the databases and collections which need to be migrated to the currently configured data model (mandatory if not -m or --migrate)
    -m, --migrate                      migrates to the currently configured data model all the databases and collections which has been created using a distinct data model (mandatory if not -a or --analysis)
    -v, --verbose [documents]          shows migration progress information if the number of documents to migrate in the collection is bigger or equal to the optional value passed (1 if no value passed)
    -r, --remove-collection            the original data model collection will be removed to avoid conflict if migrating back to that data model in the future
    -u, --update-collection            the migration will take place even if the target collections already exist combining the data of the original and target collections (use this option with special care since the migration operation is not idempotent for the aggregated data collections)
    -f, --full                         the migration will continue with the pending collections in case a previous collection throws an error and cannot be migrated (it is recommended to be used with the -r option to avoid subsequent  migrations of the same aggregated data collections)
    -d, --database <databaseName>      only this database will be taken into consideration for the analysis and/or migration process
    -c, --collection <collectionName>  only this collection will be taken info consideration, a database is mandatory if a collection is set
    -x, --dictionary <dictionary>      the path to a file including a dictionary to resolve the names of the collections to be migrated to their associated data (i.e., service path, entity id, entity type, attribute name and attribute type) (it is expected as a CSV file with lines including the following info: <collection-name>,<service-path>,<entity-id>,<entity-type>,<attribute-name>,<attribute-type>, some of which may not apply and can be left as blank)

```

--------------------------------

### STH Database Model Tool Usage

Source: https://fiware-sth-comet.readthedocs.io/en/latest/data-migration

This command displays the help information for the STH database model tool, outlining available options for data model analysis and migration.

```bash
./bin/sthDatabaseModelTool

```

--------------------------------

### Query historical context information (Deprecated V1 API)

Source: https://fiware-sth-comet.readthedocs.io/en/latest/raw-data-retrieval

This example shows a GET request to the deprecated STH V1 API for historical context data. It uses a different URL structure compared to the V2 API and provides an example of the response format for this older version.

```http
GET http://<sth-host>:<sth-port>/STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attrName>?hLimit=3&hOffset=0&dateFrom=2016-01-01T00:00:00.000Z&dateTo=2016-01-31T23:59:59.999Z
```

```json
{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "attrName",
                        "values": [
                            {
                                "recvTime": "2016-01-14T13:43:33.306Z",
                                "attrValue": "21.28"
                            },
                            {
                                "recvTime": "2016-01-14T13:43:34.636Z",
                                "attrValue": "23.42"
                            },
                            {
                                "recvTime": "2016-01-14T13:43:35.424Z",
                                "attrValue": "22.12"
                            }
                        ]
                    }
                ],
                "id": "entityId",
                "isPattern": false
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}
```

--------------------------------

### Query historical context information (V2 API)

Source: https://fiware-sth-comet.readthedocs.io/en/latest/raw-data-retrieval

This example demonstrates a GET request to the STH V2 API for historical raw context information. It includes common parameters like entity ID, attribute name, type, pagination (hLimit, hOffset), and date range. The response structure for historical data is also shown.

```http
GET http://<sth-host>:<sth-port>/STH/v2/entities/<entityId>/attrs/<attrName>?type=<entityType>&hLimit=3&hOffset=0&dateFrom=2016-01-01T00:00:00.000Z&dateTo=2016-01-31T23:59:59.999Z
```

```json
{
    "type": "StructuredValue",
    "values": [
        {
            "recvTime": "2016-01-14T13:43:33.306Z",
            "attrValue": "21.28"
        },
        {
            "recvTime": "2016-01-14T13:43:34.636Z",
            "attrValue": "23.42"
        },
        {
            "recvTime": "2016-01-14T13:43:35.424Z",
            "attrValue": "22.12"
        }
    ]
}
```

--------------------------------

### Run STH Component with Docker Compose (Bash)

Source: https://fiware-sth-comet.readthedocs.io/en/latest/installation

This snippet shows how to run the STH component using Docker Compose. It includes commands for both foreground and detached modes, facilitating easy testing and deployment. A MongoDB instance is included.

```bash
sudo docker-compose -f docker-compose.yml up
sudo docker-compose -f docker-compose.yml up -d

```

--------------------------------

### Build Local Docker Image for STH Component (Bash)

Source: https://fiware-sth-comet.readthedocs.io/en/latest/installation

These commands illustrate how to build a local Docker image for the STH component. The first command uses the default NodeJS version, while the second allows specifying an alternative version using a build argument.

```bash
sudo docker build -f Dockerfile .
sudo docker build --build-arg NODEJS_VERSION=0.10.46 -f Dockerfile .

```

--------------------------------

### Subscription with TimeInstant Metadata - Bash

Source: https://context7.com/context7/fiware-sth-comet_readthedocs_io_en/llms.txt

This subscription example configures STH-Comet to use the `TimeInstant` metadata provided by Orion as the timestamp for stored data, instead of the reception time. This ensures accurate time-series analysis by using the actual measurement time.

```bash
# Subscription with TimeInstant metadata (use measure generation time instead of reception time)
curl -X POST "http://orion-broker:1026/v2/subscriptions" \
  -H "Content-Type: application/json" \
  -H "Fiware-Service: factory" \
  -H "Fiware-ServicePath: /production" \
  -d '{
    "description": "STH subscription with TimeInstant",
    "subject": {
      "entities": [
        {
          "id": "Machine001",
          "type": "Machine"
        }
      ],
      "condition": {
        "attrs": ["power"]
      }
    },
    "notification": {
      "http": {
        "url": "http://sth-comet:8666/notify"
      },
      "attrs": ["power"],
      "attrsFormat": "legacy",
      "metadata": ["TimeInstant"]
    }
  }'
```

--------------------------------

### Synchronize Local Master Branch - Bash

Source: https://fiware-sth-comet.readthedocs.io/en/latest/contribution-guidelines

Synchronizes your local 'master' branch with the 'master' branch of the main FIWARE STH-Comet repository. This ensures your fork is up-to-date before starting new work.

```bash
git checkout master
git fetch fiware-sth-comet
git rebase fiware-sth-comet/master
```

--------------------------------

### Migrate Data Model

Source: https://fiware-sth-comet.readthedocs.io/en/latest/data-migration

Executes the migration of databases and collections to the currently configured data model. It is recommended to run this after performing an analysis (-a) and optionally without forcing updates (-u) to avoid data conflicts.

```bash
LOGOPS_FORMAT=dev DATA_MODEL=collection-per-service-path ./bin/sthDatabaseModelTool -a -m

```

--------------------------------

### Numeric Aggregated Data Schema Example

Source: https://fiware-sth-comet.readthedocs.io/en/latest/data-models-schemas

This JSON object illustrates the schema for an aggregated data document when dealing with numeric attribute values. It includes fields for origin, resolution, and points, where each point contains aggregation metrics like sum, sum2, min, and max. The resolution in this example is set to 'day'.

```json
{
    "_id": {
        "origin": "2016-10-01T00:00:00Z",
        "resolution": "day"
    },
    "points": [
        {
            "offset": 5,
            "samples": 1,
            "sum": 333,
            "sum2": 110889,
            "min": 333,
            "max": 333
        }
    ]
}
```

--------------------------------

### Analyze Data Model for Migration

Source: https://fiware-sth-comet.readthedocs.io/en/latest/data-migration

Performs an analysis of the current data model, identifying databases and collections that need migration to the specified data model. This command is a prerequisite for migration.

```bash
LOGOPS_FORMAT=dev DATA_MODEL=collection-per-service-path ./bin/sthDatabaseModelTool -a

```

--------------------------------

### GET /STH/v2/entities/<entityId>/attrs/<attrName>

Source: https://fiware-sth-comet.readthedocs.io/en/latest/raw-data-retrieval

Retrieves historical raw context information for a specific entity and attribute. Supports pagination and filtering by date.

```APIDOC
## GET /STH/v2/entities/<entityId>/attrs/<attrName>

### Description
Retrieves historical raw context information for a specific entity and attribute. Supports pagination and filtering by date.

### Method
GET

### Endpoint
`http://<sth-host>:<sth-port>/STH/v2/entities/<entityId>/attrs/<attrName>`

### Parameters
#### Path Parameters
- **entityId** (string) - Required - The ID of the entity.
- **attrName** (string) - Required - The name of the attribute.

#### Query Parameters
- **type** (string) - Required - The type of the entity.
- **hLimit** (integer) - Optional - The number of entries per page. Mandatory if `lastN` is not provided.
- **hOffset** (integer) - Optional - The offset to apply to the requested search. Mandatory if `lastN` is not provided.
- **dateFrom** (string) - Optional - The starting date and time (ISO 8601 format).
- **dateTo** (string) - Optional - The final date and time (ISO 8601 format).
- **lastN** (integer) - Optional - Only the requested last entries will be returned. Mandatory if `hLimit` and `hOffset` are not provided.
- **file type** (string) - Optional - The desired file type for the response. Currently, only `csv` is supported.
- **count** (boolean) - Optional - If `true`, the response will include the `Fiware-Total-Count` header. Defaults to `false`.

### Request Example
```json
{
  "example": "http://<sth-host>:<sth-port>/STH/v2/entities/urn:ngsi:MyEntity:123/attrs/temperature?type=MyEntityType&hLimit=3&hOffset=0&dateFrom=2016-01-01T00:00:00.000Z&dateTo=2016-01-31T23:59:59.999Z"
}
```

### Response
#### Success Response (200)
- **type** (string) - The type of the response, e.g., "StructuredValue".
- **values** (array) - An array of attribute values, each containing `recvTime` and `attrValue`.

#### Response Example
```json
{
    "type": "StructuredValue",
    "values": [
        {
            "recvTime": "2016-01-14T13:43:33.306Z",
            "attrValue": "21.28"
        },
        {
            "recvTime": "2016-01-14T13:43:34.636Z",
            "attrValue": "23.42"
        },
        {
            "recvTime": "2016-01-14T13:43:35.424Z",
            "attrValue": "22.12"
        }
    ]
}
```
```

--------------------------------

### Run STH Component in Docker with PM2 Enabled (Bash)

Source: https://fiware-sth-comet.readthedocs.io/en/latest/installation

This command demonstrates how to run the STH component within a Docker container with the PM2 process manager enabled by setting the `PM2_ENABLED` environment variable. This is useful for managing Node.js processes in containerized environments.

```bash
docker run --name sth -e PM2_ENABLED=true -d fiware/fiware-sth-comet

```

--------------------------------

### Query String Aggregated Time Series (HTTP GET)

Source: https://fiware-sth-comet.readthedocs.io/en/latest/aggregated-data-retrieval

Illustrates an HTTP GET request URL for querying aggregated time series data of string type, using the 'occur' aggregation method. It shows the necessary parameters and provides an example of the expected JSON response structure for string data, detailing occurrences of different string values.

```HTTP
GET http://<sth-host>:<sth-port>/STH/v2/entities/<entityId>/attrs/<attrName>?type=<entityType>&aggrMethod=occur&aggrPeriod=second&dateFrom=2016-01-22T00:00:00.000Z&dateTo=2016-01-22T23:59:59.999Z
```

```JSON
{
    "type": "StructuredValue",
    "values": [
        {
            "_id": {
                "origin": "2016-01-22T02:46:00.000Z",
                "resolution": "second"
            },
            "points": [
                {
                    "offset": 35,
                    "samples": 34,
                    "occur": {
                        "string01": 7,
                        "string02": 4,
                        "string03": 5,
                        "string04": 6,
                        "string05": 12
                    }
                }
            ]
        }
    ]
}
```

--------------------------------

### Deprecated: GET /STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attrName>

Source: https://fiware-sth-comet.readthedocs.io/en/latest/raw-data-retrieval

Deprecated endpoint for retrieving historical raw context information using the old V1 API. It is recommended to use the V2 endpoint instead.

```APIDOC
## GET /STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attrName>

### Description
Deprecated endpoint for retrieving historical raw context information using the old V1 API. It is recommended to use the V2 endpoint instead.

### Method
GET

### Endpoint
`http://<sth-host>:<sth-port>/STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attrName>`

### Parameters
#### Path Parameters
- **entityType** (string) - Required - The type of the entity.
- **entityId** (string) - Required - The ID of the entity.
- **attrName** (string) - Required - The name of the attribute.

#### Query Parameters
- **hLimit** (integer) - Optional - The number of entries per page.
- **hOffset** (integer) - Optional - The offset to apply to the requested search.
- **dateFrom** (string) - Optional - The starting date and time (ISO 8601 format).
- **dateTo** (string) - Optional - The final date and time (ISO 8601 format).

### Request Example
```json
{
  "example": "http://<sth-host>:<sth-port>/STH/v1/contextEntities/type/MyEntityType/id/urn:ngsi:MyEntity:123/attributes/temperature?hLimit=3&hOffset=0&dateFrom=2016-01-01T00:00:00.000Z&dateTo=2016-01-31T23:59:59.999Z"
}
```

### Response
#### Success Response (200)
- **contextResponses** (array) - An array containing context response objects.
  - **contextElement** (object) - Details about the context element.
    - **attributes** (array) - An array of attributes for the context element.
      - **name** (string) - The name of the attribute.
      - **values** (array) - An array of attribute values, each containing `recvTime` and `attrValue`.
    - **id** (string) - The ID of the context element.
    - **isPattern** (boolean) - Indicates if the ID is a pattern.
  - **statusCode** (object) - The status code of the response.
    - **code** (string) - The HTTP status code.
    - **reasonPhrase** (string) - The reason phrase for the status code.

#### Response Example
```json
{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "attrName",
                        "values": [
                            {
                                "recvTime": "2016-01-14T13:43:33.306Z",
                                "attrValue": "21.28"
                            },
                            {
                                "recvTime": "2016-01-14T13:43:34.636Z",
                                "attrValue": "23.42"
                            },
                            {
                                "recvTime": "2016-01-14T13:43:35.424Z",
                                "attrValue": "22.12"
                            }
                        ]
                    }
                ],
                "id": "entityId",
                "isPattern": false
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}
```
```

--------------------------------

### Query Numeric Aggregated Time Series (HTTP GET)

Source: https://fiware-sth-comet.readthedocs.io/en/latest/aggregated-data-retrieval

Demonstrates a typical HTTP GET request URL to query aggregated time series data for a numeric attribute. It includes placeholders for entity ID, attribute name, entity type, aggregation method, aggregation period, and date range. The response structure for numeric data is also shown.

```HTTP
GET http://<sth-host>:<sth-port>/STH/v2/entities/<entityId>/attrs/<attrName>?type=<entityType>&aggrMethod=sum&aggrPeriod=second&dateFrom=2016-01-01T00:00:00.000Z&dateTo=2016-01-01T23:59:59.999Z
```

```JSON
{
    "type": "StructuredValue",
    "values": [
        {
            "_id": {
                "origin": "2016-01-01T02:46:00.000Z",
                "resolution": "second"
            },
            "points": [
                {
                    "offset": 13,
                    "samples": 1,
                    "sum": 34.59
                }
            ]
        }
    ]
}
```

--------------------------------

### Raw Data Document Example - STH-Comet

Source: https://context7.com/context7/fiware-sth-comet_readthedocs_io_en/llms.txt

This JSON structure represents a single raw data record as stored by STH-Comet. It includes a unique identifier, the reception timestamp, the attribute type, and its numerical value. This format is fundamental for individual sensor readings.

```json
{
    "_id": "57f4d8657905c024630c41dc",
    "recvTime": "2016-10-05T10:39:33.291Z",
    "attrType": "Number",
    "attrValue": "21.5"
}
```

--------------------------------

### STH-Comet Data Model Configuration (Bash)

Source: https://context7.com/context7/fiware-sth-comet_readthedocs_io_en/llms.txt

This section details how to configure STH-Comet's data model strategy, affecting MongoDB collection organization. Options include 'collection-per-service-path', 'collection-per-entity' (default), and 'collection-per-attribute', with examples of resulting MongoDB structures and raw data documents.

```bash
# Collection per Service Path (groups all entities by service path)
DATA_MODEL=collection-per-service-path ./bin/sth

# MongoDB structure:
# Database: sth_hotel
# Collections:
#   - sth_/floor1 (raw data for all entities in /floor1)
#   - sth_/floor1.aggr (aggregated data for all entities in /floor1)

# Raw data document example:
# {
#     "_id": "57f4d8657905c024630c41dc",
#     "recvTime": "2016-10-05T10:39:33.291Z",
#     "entityId": "Room001",
#     "entityType": "Room",
#     "attrName": "temperature",
#     "attrType": "Number",
#     "attrValue": "21.5"
# }
```

```bash
# Collection per Entity (default - one collection per entity)
DATA_MODEL=collection-per-entity ./bin/sth

# MongoDB structure:
# Database: sth_hotel
# Collections:
#   - sth_/floor1_Room_Room001 (raw data for Room001)
#   - sth_/floor1_Room_Room001.aggr (aggregated data for Room001)

# Raw data document example:
# {
#     "_id": "57f4d8657905c024630c41dc",
#     "recvTime": "2016-10-05T10:39:33.291Z",
#     "attrName": "temperature",
#     "attrType": "Number",
#     "attrValue": "21.5"
# }
```

```bash
# Collection per Attribute (finest granularity)
DATA_MODEL=collection-per-attribute ./bin/sth

# MongoDB structure:
# Database: sth_hotel
# Collections:

```

--------------------------------

### GET /STH/v2/entities/{entityId}/attrs/{attrName} - Raw Data Retrieval

Source: https://context7.com/context7/fiware-sth-comet_readthedocs_io_en/llms.txt

Retrieve historical raw context information for a specific entity attribute with pagination and time filtering. Supports retrieving data by page, last N entries, total count, and exporting as CSV.

```APIDOC
## GET /STH/v2/entities/{entityId}/attrs/{attrName}

### Description
Retrieve historical raw context information for a specific entity attribute with pagination and time filtering.

### Method
GET

### Endpoint
/STH/v2/entities/{entityId}/attrs/{attrName}

### Parameters
#### Path Parameters
- **entityId** (string) - Required - The ID of the entity.
- **attrName** (string) - Required - The name of the attribute.

#### Query Parameters
- **type** (string) - Required - The type of the entity.
- **hLimit** (integer) - Optional - The number of entries per page.
- **hOffset** (integer) - Optional - The offset for pagination.
- **lastN** (integer) - Optional - The number of the last entries to retrieve.
- **dateFrom** (string) - Optional - The start date for filtering (ISO 8601 format).
- **dateTo** (string) - Optional - The end date for filtering (ISO 8601 format).
- **count** (boolean) - Optional - If true, returns the total number of entries in the `Fiware-Total-Count` header.
- **filetype** (string) - Optional - The file type for export (e.g., `csv`).

### Headers
- **Fiware-Service** (string) - Required - The service context.
- **Fiware-ServicePath** (string) - Required - The service path context.

### Request Example
```bash
curl -X GET "http://localhost:8666/STH/v2/entities/Room001/attrs/temperature?type=Room&hLimit=3&hOffset=0&dateFrom=2016-01-01T00:00:00.000Z&dateTo=2016-01-31T23:59:59.999Z" \
  -H "Fiware-Service: hotel" \
  -H "Fiware-ServicePath: /floor1"
```

### Response
#### Success Response (200)
- **type** (string) - The type of the attribute value.
- **values** (array) - An array of historical data points.
  - **recvTime** (string) - The timestamp of the data point.
  - **attrValue** (any) - The value of the attribute.

#### Response Example
```json
{
    "type": "StructuredValue",
    "values": [
        {
            "recvTime": "2016-01-14T13:43:33.306Z",
            "attrValue": "21.28"
        },
        {
            "recvTime": "2016-01-14T13:43:34.636Z",
            "attrValue": "23.42"
        },
        {
            "recvTime": "2016-01-14T13:43:35.424Z",
            "attrValue": "22.12"
        }
    ]
}
```
```

--------------------------------

### GET /STH/v2/entities/{entityId}/attrs/{attrName} - Aggregated Data Retrieval

Source: https://context7.com/context7/fiware-sth-comet_readthedocs_io_en/llms.txt

Query aggregated time series statistics for numeric attributes across different time resolutions. Supports various aggregation methods like sum, min, max, and averaging.

```APIDOC
## GET /STH/v2/entities/{entityId}/attrs/{attrName} - Aggregated Data Retrieval

### Description
Query aggregated time series statistics for numeric attributes across different time resolutions. Supports various aggregation methods like sum, min, max, and averaging.

### Method
GET

### Endpoint
/STH/v2/entities/{entityId}/attrs/{attrName}

### Parameters
#### Path Parameters
- **entityId** (string) - Required - The ID of the entity.
- **attrName** (string) - Required - The name of the attribute.

#### Query Parameters
- **type** (string) - Required - The type of the entity.
- **aggrMethod** (string) - Required - The aggregation method(s) (e.g., `sum`, `min`, `max`, `avg`, `all`). Can be a comma-separated list.
- **aggrPeriod** (string) - Required - The aggregation period (e.g., `second`, `minute`, `hour`, `day`, `month`).
- **dateFrom** (string) - Optional - The start date for filtering (ISO 8601 format).
- **dateTo** (string) - Optional - The end date for filtering (ISO 8601 format).

### Headers
- **Fiware-Service** (string) - Required - The service context.
- **Fiware-ServicePath** (string) - Required - The service path context.

### Request Example
```bash
curl -X GET "http://localhost:8666/STH/v2/entities/Room001/attrs/temperature?type=Room&aggrMethod=sum&aggrPeriod=second&dateFrom=2016-01-01T00:00:00.000Z&dateTo=2016-01-01T23:59:59.999Z" \
  -H "Fiware-Service: hotel" \
  -H "Fiware-ServicePath: /floor1"
```

### Response
#### Success Response (200)
- **type** (string) - The type of the attribute value.
- **values** (array) - An array of aggregated data points.
  - **_id** (object) - Identifier for the aggregated data.
    - **origin** (string) - The start time of the aggregation period.
    - **resolution** (string) - The aggregation resolution.
  - **points** (array) - Array of aggregated data points within the period.
    - **offset** (integer) - The time offset within the aggregation period.
    - **samples** (integer) - The number of samples aggregated.
    - **min** (number) - Minimum value (if requested).
    - **max** (number) - Maximum value (if requested).
    - **sum** (number) - Sum of values (if requested).
    - **avg** (number) - Average value (if requested).

#### Response Example
```json
{
    "type": "StructuredValue",
    "values": [
        {
            "_id": {
                "origin": "2016-01-01T02:46:00.000Z",
                "resolution": "second"
            },
            "points": [
                {
                    "offset": 13,
                    "samples": 1,
                    "sum": 34.59
                }
            ]
        }
    ]
}
```
```

--------------------------------

### Aggregated Context Information (Deprecated)

Source: https://fiware-sth-comet.readthedocs.io/en/latest/aggregated-data-retrieval

This section details the deprecated API endpoints for retrieving aggregated context information. It covers two primary aggregation methods: sum and occurrence, with specific examples for each.

```APIDOC
## GET /STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attrName>

### Description
Retrieves aggregated context information for a specific entity attribute over a given period. This API is deprecated and should not be used in new implementations.

### Method
GET

### Endpoint
`http://<sth-host>:<sth-port>/STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attrName>`

### Query Parameters
- **aggrMethod** (string) - Required - The aggregation method to use (e.g., `sum`, `occur`).
- **aggrPeriod** (string) - Required - The period for aggregation (e.g., `second`, `minute`, `hour`).
- **dateFrom** (string) - Required - The start date and time for the aggregation period in ISO 8601 format.
- **dateTo** (string) - Required - The end date and time for the aggregation period in ISO 8601 format.

### Request Example
**For 'sum' aggregation:**
`http://<sth-host>:<sth-port>/STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attrName>?aggrMethod=sum&aggrPeriod=second&dateFrom=2016-01-01T00:00:00.000Z&dateTo=2016-01-01T23:59:59.999Z`

**For 'occur' aggregation:**
`http://<sth-host>:<sth-port>/STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attrName>?aggrMethod=occur&aggrPeriod=second&dateFrom=2016-01-22T00:00:00.000Z&dateTo=2016-01-22T23:59:59.999Z`

### Response
#### Success Response (200)
Returns a JSON object containing the aggregated context information. The structure varies based on the `aggrMethod`.

#### Response Example (for 'sum')
```json
{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "attrName",
                        "values": [
                            {
                                "_id": {
                                    "origin": "2016-01-01T02:46:00.000Z",
                                    "resolution": "second"
                                },
                                "points": [
                                    {
                                        "offset": 13,
                                        "samples": 1,
                                        "sum": 34.59
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "id": "entityId",
                "isPattern": false
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}
```

#### Response Example (for 'occur')
```json
{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "attrName",
                        "values": [
                            {
                                "_id": {
                                    "origin": "2016-01-22T02:46:00.000Z",
                                    "resolution": "second"
                                },
                                "points": [
                                    {
                                        "offset": 35,
                                        "samples": 34,
                                        "occur": {
                                            "string01": 7,
                                            "string02": 4,
                                            "string03": 5,
                                            "string04": 6,
                                            "string05": 12
                                        }
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "id": "entityId",
                "isPattern": false
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}
```

### Notes
- Textual values containing `$` or `.` characters in attributes used for aggregation will be substituted with their Javascript Unicode equivalents (`\uFF04` for `$` and `\uFF0E` for `.`) due to MongoDB limitations.
```

--------------------------------

### Force Data Model Migration with Conflict

Source: https://fiware-sth-comet.readthedocs.io/en/latest/data-migration

This command forces a data model migration when the target collection already exists and contains valuable data. It combines the original data with the existing data in the target collection. The `-r` option can be used to automatically remove the original collection after a successful migration.

```shell
LOGOPS_FORMAT=dev DATA_MODEL=collection-per-service-path ./bin/sthDatabaseModelTool -a -m -d <database_name> -c <original_data_model_collection_to_be_migrated> -u
```

--------------------------------

### Textual Aggregated Data Schema Example

Source: https://fiware-sth-comet.readthedocs.io/en/latest/data-models-schemas

This JSON object demonstrates the schema for an aggregated data document when handling textual attribute values. Similar to the numeric schema, it includes origin and resolution, but the 'points' object contains an 'occur' field detailing the count of each textual value occurrence over time.

```json
{
    "_id": {
        "origin": "2016-10-01T00:00:00Z",
        "resolution": "day"
    },
    "points": [
        {
            "offset": 5,
            "samples": 1,
            "occur": {
                "text1": 1,
                "text2": 4,
                "text3": 7
            }
        }
    ]
}
```

--------------------------------

### Get Historical Aggregated Time Series Context Information

Source: https://fiware-sth-comet.readthedocs.io/en/latest/aggregated-data-retrieval

This endpoint retrieves historical aggregated time series context information for a specific entity and attribute. It supports various aggregation methods, periods, and date ranges.

```APIDOC
## GET /STH/v2/entities/<entityId>/attrs/<attrName>

### Description
Retrieves historical aggregated time series context information for a specified entity and attribute. Supports filtering by type, aggregation method, aggregation period, and date range.

### Method
GET

### Endpoint
`/STH/v2/entities/<entityId>/attrs/<attrName>`

### Parameters
#### Path Parameters
- **entityId** (string) - Required - The ID of the entity.
- **attrName** (string) - Required - The name of the attribute.

#### Query Parameters
- **type** (string) - Required - The entity type.
- **aggrMethod** (string) - Required - The aggregation method. Supported values: `max`, `min`, `sum`, `sum2` (for numeric), `occur` (for string). Can accept multiple values separated by comma (e.g., `min,max`) or `all` for all methods.
- **aggrPeriod** (string) - Required - The aggregation period or resolution. Possible values: `month`, `day`, `hour`, `minute`, `second`.
- **dateFrom** (string) - Optional - The starting date and time in ISO 8601 format.
- **dateTo** (string) - Optional - The final date and time in ISO 8601 format.

### Request Example
```json
{
  "example": "http://<sth-host>:<sth-port>/STH/v2/entities/someEntityId/attrs/someAttrName?type=EntityType&aggrMethod=sum&aggrPeriod=second&dateFrom=2016-01-01T00:00:00.000Z&dateTo=2016-01-01T23:59:59.999Z"
}
```

### Response
#### Success Response (200)
- **type** (string) - The type of the response, typically "StructuredValue".
- **values** (array) - An array of aggregated data points.
  - **_id** (object) - Identifier for the aggregated data point.
    - **origin** (string) - The origin timestamp of the aggregation.
    - **resolution** (string) - The aggregation resolution.
  - **points** (array) - Array of data points within the aggregation.
    - **offset** (integer) - The time offset within the resolution.
    - **samples** (integer) - The number of samples.
    - **sum** (number) - The sum of values (for numeric attributes).
    - **occur** (object) - Object containing occurrence counts for string attributes.

#### Response Example (Numeric Attribute)
```json
{
  "example": {
    "type": "StructuredValue",
    "values": [
      {
        "_id": {
          "origin": "2016-01-01T02:46:00.000Z",
          "resolution": "second"
        },
        "points": [
          {
            "offset": 13,
            "samples": 1,
            "sum": 34.59
          }
        ]
      }
    ]
  }
}
```

#### Response Example (String Attribute)
```json
{
  "example": {
    "type": "StructuredValue",
    "values": [
      {
        "_id": {
          "origin": "2016-01-22T02:46:00.000Z",
          "resolution": "second"
        },
        "points": [
          {
            "offset": 35,
            "samples": 34,
            "occur": {
              "string01": 7,
              "string02": 4,
              "string03": 5,
              "string04": 6,
              "string05": 12
            }
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### STH-Comet Docker Deployment (Bash)

Source: https://context7.com/context7/fiware-sth-comet_readthedocs_io_en/llms.txt

Instructions for deploying STH-Comet using Docker, including cloning the repository, using docker-compose, running official images with environment variables, building custom images, and setting up a full stack with Orion and MongoDB.

```bash
# Clone repository
git clone https://github.com/telefonicaid/fiware-sth-comet.git
cd fiware-sth-comet/
```

```bash
# Deploy with docker-compose (includes MongoDB)
sudo docker-compose -f docker-compose.yml up -d
```

```bash
# Run official Docker image from FIWARE Docker Hub
docker run -d --name sth-comet \
  -p 8666:8666 \
  -e DB_URI=mongodb:27017 \
  -e STH_PORT=8666 \
  -e DATA_MODEL=collection-per-entity \
  fiware/sth-comet
```

```bash
# Run with PM2 process manager enabled
docker run -d --name sth-comet \
  -p 8666:8666 \
  -e PM2_ENABLED=true \
  -e DB_URI=mongodb:27017 \
  fiware/sth-comet
```

```bash
# Build custom Docker image with specific Node.js version
sudo docker build --build-arg NODEJS_VERSION=16.20.0 -f Dockerfile -t my-sth-comet .
```

```bash
# Run custom image with full configuration
docker run -d --name sth-comet-custom \
  -p 8666:8666 \
  -e STH_PORT=8666 \
  -e DB_URI=mongodb:27017 \
  -e DB_USERNAME=sth_user \
  -e DB_PASSWORD=secure_pass \
  -e DATA_MODEL=collection-per-entity \
  -e SHOULD_STORE=both \
  -e LOGOPS_LEVEL=INFO \
  -e TRUNCATION_EXPIRE_AFTER_SECONDS=2592000 \
  my-sth-comet
```

```bash
# Docker Compose with full stack (Orion + MongoDB + STH-Comet)
cat > docker-compose-full.yml <<EOF
version: "3"
services:
  mongodb:
    image: mongo:4.4
    ports:
      - "27017:27017"
    volumes:
      - mongo-data:/data/db

  orion:
    image: fiware/orion:3.7.0
    ports:
      - "1026:1026"
    depends_on:
      - mongodb
    command: -dbhost mongodb

  sth-comet:
    image: fiware/sth-comet
    ports:
      - "8666:8666"
    depends_on:
      - mongodb
    environment:
      - STH_PORT=8666
      - DB_URI=mongodb:27017
      - DATA_MODEL=collection-per-entity

volumes:
  mongo-data:
EOF

docker-compose -f docker-compose-full.yml up -d
```

--------------------------------

### Clone Repository - Bash

Source: https://fiware-sth-comet.readthedocs.io/en/latest/contribution-guidelines

Clones the forked STH-Comet repository to your local machine. This is the first step after forking the main repository.

```bash
git clone https://github.com/your-github-username/fiware-sth-comet.git
```

--------------------------------

### STH Database Name Mapper Tool Usage Help

Source: https://fiware-sth-comet.readthedocs.io/en/latest/name-mapping

Displays the available options and usage instructions for the `sthDatabaseNameMapperTool`. This helps users understand how to perform mapping (`-m`), unmapping (`-u`), and force operations (`-f`).

```shell
Usage: sthDatabaseNameMapperTool [options]

  Options:

    -h, --help                         output usage information
    -V, --version                      output the version number
    -m, --map                          Shows a report regarding the result of the mapping process if applied to databases and collections of a specific STH instance (either the -m or -u options are mandatory)
    -u, --unmap                        Shows a report regarding the result of the unmapping process if applied to databases and collections of a specific STH instance (either the -e or -d options are mandatory)
    -f, --force                        Forces the mapping (-m) or unmapping (-u) process and consequently the databases will be renamed

```

--------------------------------

### Check Source Code Style - npm

Source: https://fiware-sth-comet.readthedocs.io/en/latest/contribution-guidelines

Runs ESLint to check the source code style according to the provided .eslintrc.json configuration. This command helps ensure code adheres to project standards.

```bash
npm run lint
```
Tokens:
Raw