Main API Classes

The Cumulocity Python API's main API classes provide access to various contexts within the Cumulocity REST API. Use it to read existing data or modify in bulk.

See also the Object model section for object creation and object-oriented access in general.

---

Inventory

Provides access to the Inventory API.

This class can be used for get, search for, create, update and delete managed objects within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Inventory-API

apply_to(object_model: ManagedObject | dict, *object_ids)

Apply a change to multiple already existing objects.

Applies the details of a model object to a set of already existing managed objects.

Note: This will take the full details, not just the updates.

Parameters:

Name	Type	Description	Default
object_model	ManagedObject | dict	ManagedObject instance holding the change structure (e.g. a specific fragment) or simply a dictionary representing the diff JSON.	required
*object_ids	str	a collection of ID of already existing managed objects within the database	()

create(*objects: ManagedObject)

Create managed objects within the database.

Parameters:

Name	Type	Description	Default
*objects	ManagedObject	collection of ManagedObject instances	()

get(id: str, with_children: bool = None, with_children_count: bool = None, skip_children_names: bool = None, with_parents: bool = None, with_latest_values: bool = None, **kwargs) -> ManagedObject

Retrieve a specific managed object from the database.

Parameters:

Name	Type	Description	Default
id	str	Cumulocity ID of the managed object	required
with_children	bool	Whether children with ID and name should be included with each returned object	None
with_children_count	bool	When set to true, the returned result will contain the total number of children in the respective child additions, assets and devices sub fragments.	None
skip_children_names	bool	If true, returned references of child devices won't contain their names.	None
with_parents	bool	Whether to include a device's parents.	None
with_latest_values	bool	If true the platform includes the fragment `c8y_LatestMeasurements, which contains the latest measurement values reported by the device to the platform.	None

Returns:

Type	Description
ManagedObject	A ManagedObject instance

Raises:

Type	Description
KeyError	if the ID is not defined within the database

get_all(expression: str = None, query: str = None, ids: list[str | int] = None, order_by: str = None, type: str = None, parent: str = None, fragment: str = None, fragments: list[str] = None, name: str = None, owner: str = None, text: str = None, only_roots: str = None, with_children: bool = None, with_children_count: bool = None, skip_children_names: bool = None, with_groups: bool = None, with_parents: bool = None, with_latest_values: bool = None, reverse: bool = None, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> List[ManagedObject]

Query the database for managed objects and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

Returns:

Type	Description
List[ManagedObject]	List of ManagedObject instances

get_by(expression: str = None, query: str = None, ids: list[str | int] = None, order_by: str = None, type: str = None, parent: str = None, fragment: str = None, fragments: list[str] = None, name: str = None, owner: str = None, text: str = None, only_roots: str = None, with_children: bool = None, with_children_count: bool = None, skip_children_names: bool = None, with_groups: bool = None, with_parents: bool = None, with_latest_values: bool = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> ManagedObject

Query the database for a specific managed object.

This function is a special version of the select function assuming a single result being returned by the query.

Returns:

Type	Description
ManagedObject	A ManagedObject instance

Raises:

Type	Description
ValueError	if the query did not return any or more than one result.

get_count(expression: str = None, query: str = None, ids: List[str | int] = None, type: str = None, parent: str = None, fragment: str = None, fragments: list[str] = None, name: str = None, owner: str = None, text: str = None, **kwargs) -> int

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
int	Number of potential results

get_latest_availability(mo_id) -> Availability

Retrieve the latest availability information of a managed object.

Parameters:

Name	Type	Description	Default
mo_id	str	Device (managed object) ID	required

Return

DeviceAvailability object

get_supported_measurements(mo_id) -> [str]

Retrieve all supported measurements names of a specific managed object.

Parameters:

Name	Type	Description	Default
mo_id	str	Managed object ID	required

Return

List of measurement fragment names.

get_supported_series(mo_id) -> [str]

Retrieve all supported measurement series names of a specific managed object.

Parameters:

Name	Type	Description	Default
mo_id	str	Managed object ID	required

Return

List of series names.

select(expression: str = None, query: str = None, ids: list[str | int] = None, order_by: str = None, type: str = None, parent: str = None, fragment: str = None, fragments: list[str] = None, name: str = None, owner: str = None, text: str = None, only_roots: str = None, with_children: bool = None, with_children_count: bool = None, skip_children_names: bool = None, with_groups: bool = None, with_parents: bool = None, with_latest_values: bool = None, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> Generator[ManagedObject]

Query the database for managed objects and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
query	str	Complex query to execute; all other filters are ignored if such a custom query is provided	None
ids	List[str | int]	Specific object ID to select.	None
order_by	str	Field/expression to sort the results.	None
type	str	Managed object type	None
parent	str	Parent object in the asset hierarchy (ID).	None
fragment	str	Name of a present custom/standard fragment	None
fragments	list[str]	Additional fragments present within objects	None
name	str	Name of the managed object Note: The Cumulocity REST API does not support filtering for names directly; this is a convenience parameter which will translate all filters into a query string.	None
owner	str	Username of the object owner	None
text	str	Text value of any object property.	None
only_roots	bool	Whether to include only objects that don't have any parent	None
with_children	bool	Whether children with ID and name should be included with each returned object	None
with_children_count	bool	When set to true, the returned result will contain the total number of children in the respective child additions, assets and devices sub fragments.	None
skip_children_names	bool	If true, returned references of child devices won't contain their names.	None
with_groups	bool	Whether to include additional information about the groups to which the searched managed object belongs to. This results in setting the assetParents property with additional information about the groups.	None
with_parents	bool	Whether to include a device's parents.	None
with_latest_values	bool	If true the platform includes the fragment `c8y_LatestMeasurements, which contains the latest measurement values reported by the device to the platform.	None
limit	int	Limit the number of results to this number.	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Define the number of events which are read (and parsed in one chunk). This is a performance related setting.	1000
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None
as_values	str | tuple | list[str | tuple]	(*str|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	None

Returns:

Type	Description
Generator[ManagedObject]	Generator for ManagedObject instances

See also

https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language

update(*objects: ManagedObject)

Write changes to the database.

Parameters:

Name	Type	Description	Default
*objects	ManagedObject	collection of ManagedObject instances	()

See also function ManagedObject.update which parses the result.

DeviceInventory

Provides access to the Device Inventory API.

This class can be used for get, search for, create, update and delete device objects within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Inventory-API

accept(id: str)

Accept a device request.

Parameters:

Name	Type	Description	Default
id	str	Unique ID of the device (e.g. Serial, IMEI); this is not the database ID.	required

delete(*devices: Device) -> None

Delete one or more devices and the corresponding within the database.

The objects can be specified as instances of a database object (then, the id field needs to be defined) or simply as ID (integers or strings).

Note: In contrast to the regular delete function defined in class ManagedObject, this version also removes the corresponding device user from database.

Parameters:

Name	Type	Description	Default
*devices	Device	Device objects within the database specified (with defined ID).	()

get(id: str, with_children: bool = None, with_children_count: bool = None, skip_children_names: bool = None, with_parents: bool = None, with_latest_values: bool = None, **kwargs) -> Device

Retrieve a specific device object.

Parameters:

Name	Type	Description	Default
id	str	Cumulocity ID of the device object	required
with_children	bool	Whether children with ID and name should be included with each returned object	None
with_children_count	bool	When set to true, the returned result will contain the total number of children in the respective child additions, assets and devices sub fragments.	None
skip_children_names	bool	If true, returned references of child devices won't contain their names.	None
with_parents	bool	Whether to include a device's parents.	None
with_latest_values	bool	If true the platform includes the fragment `c8y_LatestMeasurements, which contains the latest measurement values reported by the device to the platform.	None

Returns:

Type	Description
Device	A Device instance

Raises:

Type	Description
KeyError	if the ID is not defined within the database

get_all(expression: str = None, query: str = None, ids: list[str | int] = None, order_by: str = None, type: str = None, parent: str = None, fragment: str = None, fragments: list[str] = None, name: str = None, owner: str = None, text: str = None, only_roots: str = None, with_children: bool = None, with_children_count: bool = None, skip_children_names: bool = None, with_groups: bool = None, with_parents: bool = None, with_latest_values: bool = None, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 100, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> List[Device]

Query the database for devices and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

Returns:

Type	Description
List[Device]	List of Device objects

get_count(expression: str = None, query: str = None, ids: list[str | int] = None, type: str = None, parent: str = None, fragment: str = None, fragments: list[str] = None, name: str = None, owner: str = None, text: str = None, **kwargs) -> int

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
int	Number of potential results

request(id: str)

Create a device request.

Parameters:

Name	Type	Description	Default
id	str	Unique ID of the device (e.g. Serial, IMEI); this is not the database ID.	required

select(expression: str = None, query: str = None, ids: list[str | int] = None, order_by: str = None, type: str = None, parent: str = None, fragment: str = None, fragments: list[str] = None, name: str = None, owner: str = None, text: str = None, only_roots: str = None, with_children: bool = None, with_children_count: bool = None, skip_children_names: bool = None, with_groups: bool = None, with_parents: bool = None, with_latest_values: bool = None, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 100, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> Generator[Device]

Query the database for devices and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (within reason).

Note: this variant doesn't allow filtering by fragment because the c8y_IsDevice fragment is automatically filtered.

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
query	str	Complex query to execute; all other filters are ignored if such a custom query is provided	None
ids	List[str | int]	Specific object ID to select.	None
type	str	Device type	None
parent	str	Parent object in the asset hierarchy (ID).	None
order_by	str	Field/expression to sort the results.	None
fragment	str	Name of a present custom/standard fragment	None
fragments	list[str]	Additional fragments present within objects	None
name	str	Name of the device Note: The Cumulocity REST API does not support filtering for names directly; this is a convenience parameter which will translate all filters into a query string.	None
owner	str	Username of the object owner	None
text	str	Text value of any object property.	None
only_roots	bool	Whether to include only objects that don't have any parent	None
with_children	bool	Whether children with ID and name should be included with each returned object	None
with_children_count	bool	When set to true, the returned result will contain the total number of children in the respective child additions, assets and devices sub fragments.	None
skip_children_names	bool	If true, returned references of child devices won't contain their names.	None
with_groups	bool	Whether to include additional information about the groups to which the searched managed object belongs to. This results in setting the assetParents property with additional information about the groups.	None
with_parents	bool	Whether to include a device's parents.	None
with_latest_values	bool	If true the platform includes the fragment `c8y_LatestMeasurements, which contains the latest measurement values reported by the device to the platform.	None
limit	int	Limit the number of results to this number.	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Define the number of events which are read (and parsed in one chunk). This is a performance related setting.	100
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None
as_values	str | tuple | list[str | tuple]	(*str|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	None

Returns:

Type	Description
Generator[Device]	Generator for Device objects

See also

https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language

Identity

Provides access to the Identity API.

https://cumulocity.com/api/core/#tag/External-IDs

https://cumulocity.com/api/core/#tag/Identity-API

create(external_id, external_type, managed_object_id)

Create a new External ID within the database.

Parameters:

Name	Type	Description	Default
external_id	str	A string to be used as ID for external use	required
external_type	str	Type of the external ID, e.g. _com_cumulocity_model_idtype_SerialNumber_	required
managed_object_id	str	Valid database ID of a managed object within Cumulocity	required

delete(external_id, external_type) -> None

Remove an External ID from the database.

Parameters:

Name	Type	Description	Default
external_id	str	A string to be used as ID for external use	required
external_type	str	Type of the external ID, e.g. _com_cumulocity_model_idtype_SerialNumber_	required

get(external_id, external_type)

Obtain a specific External ID from the database.

Parameters:

Name	Type	Description	Default
external_id	str	A string to be used as ID for external use	required
external_type	str	Type of the external ID, e.g. _com_cumulocity_model_idtype_SerialNumber_	required

Returns:

Type	Description
	ExternalID object

get_all(object_id: str) -> [ExternalId]

Read all external ID for a managed object.

Parameters:

Name	Type	Description	Default
object_id	str	Valid database ID of a managed object within Cumulocity	required

Returns:

Type	Description
[ExternalId]	A list of ExternalID instances (can be empty)

get_id(external_id, external_type)

Read the ID of the referenced managed object by its external ID.

Parameters:

Name	Type	Description	Default
external_id	str	A string to be used as ID for external use	required
external_type	str	Type of the external ID, e.g. _com_cumulocity_model_idtype_SerialNumber_	required

Returns:

Type	Description
	A database ID (string)

get_object(external_id, external_type)

Read a managed object by its external ID reference.

Parameters:

Name	Type	Description	Default
external_id	str	A string to be used as ID for external use	required
external_type	str	Type of the external ID, e.g. _com_cumulocity_model_idtype_SerialNumber_	required

Returns:

Type	Description
	ManagedObject instance

Binaries

Provides access to the Identity API.

See also: https://cumulocity.com/api/core/#tag/Binaries

create(*binaries: Binary)

Create binaries, i.e. upload files.

Each of the binaries must have a file set. The binaries are created one by one, in case of an error the state is unclear.

Parameters:

Name	Type	Description	Default
*binaries	Binary	Binaries to upload	()

Returns:

Type	Description
	The number of successfully created binaries.

Raises:

Type	Description
FileNotFoundError	if one of the file attributes within the binaries refers to an invalid file path

get_all(ids: list[str | int] = None, type: str = None, owner: str = None, child_device: str | int = None, child_asset: str | int = None, child_addition: str | int = None, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> List[Binary]

Query the database for binary objects and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

Returns:

Type	Description
List[Binary]	List of Binary instances

get_count(ids: list[str | int] = None, type: str = None, owner: str = None, child_device: str | int = None, child_asset: str | int = None, child_addition: str | int = None, **kwargs) -> int

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
int	Number of potential results

read_file(id: str) -> bytes

Read the binary content of a specific binary.

Parameters:

Name	Type	Description	Default
id	str	The database ID of the binary object.	required

Returns:

Type	Description
bytes	The binary attachment's content as bytes

select(ids: list[str | int] = None, type: str = None, owner: str = None, child_device: str | int = None, child_asset: str | int = None, child_addition: str | int = None, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> Generator[Binary]

Query the database for binaries and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filter's specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
ids	List[str | int]	Specific object ID to select.	None
type	str	Event type	None
owner	str	Username of the object owner	None
child_device	str | int	Object ID of a child device.	None
child_asset	str | int	Object ID of a child asset.	None
child_addition	str | int	Object ID of a child addition.	None
limit	int	Limit the number of results to this number.	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Define the number of events which are read (and parsed in one chunk). This is a performance related setting.	1000
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None
as_values	str | tuple | list[str | tuple]	(*str|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	None

Returns:

Type	Description
Generator[Binary]	Generator for Binary instances

update(id: str, file: str | BinaryIO, type: str = None)

Update a binary attachment.

Parameters:

Name	Type	Description	Default
id	str	ID of an existing Binary within Cumulocity	required
file	str | file - like	File to upload	required
type	str	Content type of the file (defaults to 'application/octet-stream')	None

Raises:

Type	Description
FileNotFoundError	if the file refers to an invalid path.

upload(file: str | BinaryIO, name: str, type: str) -> Binary

Upload a file.

Parameters:

Name	Type	Description	Default
file	str | file - like	File to upload	required
name	str	Virtual name of the file	required
type	str	Mimetype of the file	required

Returns:

Type	Description
Binary	A Binary instance referencing the uploaded file.

Raises:

Type	Description
FileNotFoundError	if the file refers to an invalid path.

Measurements

A wrapper for the standard Measurements API.

This class can be used for get, search for, create, update and delete measurements within the Cumulocity database.

See also: https://cumulocity.com/guides/reference/measurements/#measurement

AggregationType

Series aggregation types.

collect_series(expression: str = None, source: str = None, aggregation: str = None, series: str | Sequence[str] = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, reverse: bool = None, value: str = None, timestamps: bool | str = None, **kwargs)

Query the database for series values.

This function is functionally the same as using the get_series function with an immediate collect on the result.

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
source	str	Database ID of a source device	None
aggregation	str	Aggregation type	None
series	str | Sequence[str]	Series' to query and collect; If multiple series are collected each element in the result will be a tuple. If omitted, all available series are collected.	None
before	datetime | str	Datetime object or ISO date/time string. Only measurements assigned to a time before this date are included.	None
after	datetime | str	Datetime object or ISO date/time string. Only measurements assigned to a time after this date are included.	None
min_age	timedelta	Timedelta object. Only measurements of at least this age are included.	None
max_age	timedelta	Timedelta object. Only measurements with at most this age are included.	None
reverse	bool	Invert the order of results, starting with the most recent one.	None
value	str	Which value (min/max) to collect. If omitted, both values will be collected, grouped as 2-tuples.	None
timestamps	bool | str	Whether each element in the result list will be prepended with the corresponding timestamp. If True, the timestamp string will be included; Use 'datetime' or 'epoch' to parse the timestamp string.	None

Returns:

Type	Description
	A simple list or list of tuples (potentially nested) depending on the
	parameter combination.

See also: https://cumulocity.com/api/core/#operation/getMeasurementSeriesResource

create(*measurements)

Bulk create a collection of measurements within the database.

Parameters:

Name	Type	Description	Default
*measurements	Measurement	Collection of Measurement objects.	()

delete_by(expression: str = None, type: str = None, source: str | int = None, date_from: str | datetime = None, date_to: str | datetime = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, **kwargs)

Query the database and delete matching measurements.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (within reason).

Note: In Cumulocity, measurements are deleted asynchronously by design.

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
type	str	Alarm type	None
source	str | int	Database ID of a source device	None
before	datetime | str	Datetime object or ISO date/time string. Only measurements assigned to a time before this date are returned.	None
after	datetime | str	Datetime object or ISO date/time string. Only measurements assigned to a time after this date are returned.	None
date_from	str | datetime	Same as after	None
date_to	str | datetime	Same as before	None
min_age	timedelta	Timedelta object. Only measurements of at least this age are returned.	None
max_age	timedelta	Timedelta object. Only measurements with at most this age are returned.	None

get(measurement_id: str | int) -> Measurement

Read a specific measurement from the database.

Parameters:

Name	Type	Description	Default
measurement_id	str | int	database ID of a measurement	required

Returns:

Type	Description
Measurement	Measurement object

Raises:

Type	Description
KeyError	if the ID cannot be resolved.

get_all(expression: str = None, type: str = None, source: str | int = None, value_fragment_type: str = None, value_fragment_series: str = None, series: str = None, before: str | datetime = None, after: str | datetime = None, date_from: str | datetime = None, date_to: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, reverse: bool = None, limit: int = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> List[Measurement]

Query the database for measurements and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

Returns:

Type	Description
List[Measurement]	List of matching Measurement objects

get_count(expression: str = None, type: str = None, source: str | int = None, value_fragment_type: str = None, value_fragment_series: str = None, series: str = None, before: str | datetime = None, after: str | datetime = None, date_from: str | datetime = None, date_to: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, **kwargs) -> int

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
int	Number of potential results

get_last(expression: str = None, type: str = None, source: str | int = None, value_fragment_type: str = None, value_fragment_series: str = None, series: str = None, date_to: str | datetime = None, before: str | datetime = None, min_age: timedelta = None, **kwargs) -> Measurement | None

Query the database and return the last matching measurement.

This function is a special variant of the select function. Only the last matching result is returned.

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
type	str	Alarm type	None
source	str | int	Database ID of a source device	None
value_fragment_type	str	The series' value fragment name (e.g. c8y_Environment)	None
value_fragment_series	str	The series' name (within the value fragment, e.g. Temperature)	None
series	str	Full name of a present series within a value fragment e.g. "c8y_Environment.Temperature"	None
before	datetime | str	Datetime object or ISO date/time string. Only measurements assigned to a time before this date are returned.	None
date_to	str | datetime	Same as before	None
min_age	timedelta	Timedelta object. Only measurements of at least this age are returned.	None

Returns:

Type	Description
Measurement | None	Last matching Measurement object

get_series(expression: str = None, source: str = None, aggregation: str = None, aggregation_function: str | Sequence[str] = None, aggregation_interval: str = None, series: str | Sequence[str] = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, reverse: bool = None, **kwargs) -> Series

Query the database for a list of series and their values.

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
source	str	Database ID of a source device	None
aggregation	str	Aggregation type (e.g. HOURLY)	None
aggregation_function	str	Aggregation function, e.g. "min", "max", "avg", "sum", "count". Needs aggregation_interval.	None
aggregation_interval	str	Aggregation interval for the aggregation function.	None
series	str | Sequence[str]	Series' to query	None
before	datetime | str	Datetime object or ISO date/time string. Only measurements assigned to a time before this date are included.	None
after	datetime | str	Datetime object or ISO date/time string. Only measurements assigned to a time after this date are included.	None
min_age	timedelta	Timedelta object. Only measurements of at least this age are included.	None
max_age	timedelta	Timedelta object. Only measurements with at most this age are included.	None
reverse	bool	Invert the order of results, starting with the most recent one.	None

Returns:

Type	Description
Series	A Series object which wraps the raw JSON result but can also be
Series	used to conveniently collect the series' values.

See also: https://cumulocity.com/api/core/#operation/getMeasurementSeriesResource

select(expression: str = None, type: str = None, source: str | int = None, value_fragment_type: str = None, value_fragment_series: str = None, series: str = None, before: str | datetime = None, after: str | datetime = None, date_from: str | datetime = None, date_to: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, reverse: bool = None, limit: int = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> Generator[Measurement]

Query the database for measurements and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
type	str	Alarm type	None
source	str | int	Database ID of a source device	None
value_fragment_type	str	The series' value fragment name (e.g. c8y_Environment)	None
value_fragment_series	str	The series' name (within the value fragment, e.g. Temperature)	None
series	str	Full name of a present series within a value fragment e.g. "c8y_Environment.Temperature"	None
before	datetime | str	Datetime object or ISO date/time string. Only measurements assigned to a time before this date are returned.	None
after	datetime | str	Datetime object or ISO date/time string. Only measurements assigned to a time after this date are returned.	None
date_from	str | datetime	Same as after	None
date_to	str | datetime	Same as before	None
min_age	timedelta	Timedelta object. Only measurements of at least this age are returned.	None
max_age	timedelta	Timedelta object. Only measurements with at most this age are returned.	None
reverse	bool	Invert the order of results, starting with the most recent one.	None
limit	int	Limit the number of results to this number.	None
page_size	int	Define the number of measurements which are read (and parsed in one chunk). This is a performance related setting.	1000
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None
as_values	str | tuple | list[str | tuple]	(*str|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	None

Returns:

Type	Description
Generator[Measurement]	Generator[Measurement]: Iterable of matching Measurement objects

Events

Provides access to the Events API.

This class can be used for get, search for, create, update and delete events within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Events

apply_to(event: Event | dict, *event_ids: str)

Apply changes made to a single instance to other objects in the database.

Parameters:

Name	Type	Description	Default
event	Event | dict	Event used as model for the update or simply a dictionary representing the diff JSON.	required
*event_ids	str	Collection of ID of the events to update	()

build_attachment_path(event_id: str) -> str

Build the attachment path of a specific event.

Parameters:

Name	Type	Description	Default
event_id	int | str	Database ID of the event	required

Returns:

Type	Description
str	The relative path to the event attachment within Cumulocity.

create(*events: Event)

Create event objects within the database.

If not yet defined, this will set the event date to now in

each of the given event objects.

Parameters:

Name	Type	Description	Default
*events	Event	Collection of Event instances	()

create_attachment(event_id: str, file: str | BinaryIO, content_type: str = None) -> dict

Add an event's binary attachment.

Parameters:

Name	Type	Description	Default
event_id	str	The database ID of the event	required
file	str | BinaryIO	File-like object or a file path	required
content_type	str	Content type of the file sent (default is application/octet-stream)	None

Returns:

Type	Description
dict	Attachment details as JSON object (dict).

delete_attachment(event_id: str) -> None

Remove an event's binary attachment.

Parameters:

Name	Type	Description	Default
event_id	str	The database ID of the event	required

delete_by(expression: str = None, type: str = None, source: str = None, fragment: str = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, **kwargs)

Query the database and delete matching events.

All parameters are considered to be filters, limiting the result set to objects which meet the filter's specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
type	str	Event type	None
source	str	Database ID of a source device	None
fragment	str	Name of a present custom/standard fragment	None
before	str | datetime	Datetime object or ISO date/time string. Only events assigned to a time before this date are returned.	None
after	str | datetime	Datetime object or ISO date/time string. Only events assigned to a time after this date are returned.	None
min_age	timedelta	Minimum age for selected events.	None
max_age	timedelta	Maximum age for selected events.	None

download_attachment(event_id: str) -> bytes

Read an event's binary attachment.

Parameters:

Name	Type	Description	Default
event_id	str	The database ID of the event	required

Returns:

Type	Description
bytes	The event's binary attachment as bytes.

get(event_id: str) -> Event

Retrieve a specific object from the database.

Parameters:

Name	Type	Description	Default
event_id	str	The database ID of the event	required

Returns:

Type	Description
Event	An Event instance representing the object in the database.

get_all(expression: str = None, type: str = None, source: str = None, fragment: str = None, fragment_type: str = None, fragment_value: str = None, before: str | datetime = None, after: str | datetime = None, date_from: str | datetime = None, date_to: str | datetime = None, created_before: str | datetime = None, created_after: str | datetime = None, created_from: str | datetime = None, created_to: str | datetime = None, updated_before: str | datetime = None, updated_after: str | datetime = None, last_updated_from: str | datetime = None, last_updated_to: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, with_source_assets: bool = None, with_source_devices: bool = None, reverse: bool = False, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> List[Event]

Query the database for events and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

See select for a documentation of arguments.

Returns:

Type	Description
List[Event]	List of Event objects

get_count(expression: str = None, type: str = None, source: str = None, fragment: str = None, fragment_type: str = None, fragment_value: str = None, before: str | datetime = None, after: str | datetime = None, date_from: str | datetime = None, date_to: str | datetime = None, created_before: str | datetime = None, created_after: str | datetime = None, created_from: str | datetime = None, created_to: str | datetime = None, updated_before: str | datetime = None, updated_after: str | datetime = None, last_updated_from: str | datetime = None, last_updated_to: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, **kwargs) -> int

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
int	Number of potential results

get_last(expression: str = None, type: str = None, source: str = None, fragment: str = None, fragment_type: str = None, fragment_value: str = None, before: str | datetime = None, date_to: str | datetime = None, created_before: str | datetime = None, created_to: str | datetime = None, updated_before: str | datetime = None, last_updated_to: str | datetime = None, min_age: timedelta = None, with_source_assets: bool = None, with_source_devices: bool = None, **kwargs) -> Event | None

Retrieve the most recent event.

select(expression: str = None, type: str = None, source: str = None, fragment: str = None, fragment_type: str = None, fragment_value: str = None, before: str | datetime = None, after: str | datetime = None, date_from: str | datetime = None, date_to: str | datetime = None, created_before: str | datetime = None, created_after: str | datetime = None, created_from: str | datetime = None, created_to: str | datetime = None, updated_before: str | datetime = None, updated_after: str | datetime = None, last_updated_from: str | datetime = None, last_updated_to: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, with_source_assets: bool = None, with_source_devices: bool = None, reverse: bool = False, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> Generator[Event]

Query the database for events and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filter's specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
type	str	Event type	None
source	str	Database ID of a source device	None
fragment	str	Name of a present custom/standard fragment	None
fragment_type	str	Name of a present custom/standard fragment.	None
fragment_value	str	Value of present custom/standard fragment.	None
before	str | datetime	Datetime object or ISO date/time string. Only events assigned to a time before this date are returned.	None
after	str | datetime	Datetime object or ISO date/time string. Only events assigned to a time after this date are returned.	None
created_before	str | datetime	Datetime object or ISO date/time string. Only events changed at a time before this date are returned.	None
created_after	str | datetime	Datetime object or ISO date/time string. Only events changed at a time after this date are returned.	None
updated_before	str | datetime	Datetime object or ISO date/time string. Only events changed at a time before this date are returned.	None
updated_after	str | datetime	Datetime object or ISO date/time string. Only events changed at a time after this date are returned.	None
min_age	timedelta	Minimum age for selected events.	None
max_age	timedelta	Maximum age for selected events.	None
date_from	str | datetime	Same as after	None
date_to	str | datetime	Same as before	None
created_from	str | datetime	Same as created_after	None
created_to	str | datetime	Same as created_before	None
last_updated_from	str | datetime	Same as updated_after	None
last_updated_to	str | datetime	Same as updated_before	None
reverse	bool	Invert the order of results, starting with the most recent one.	False
with_source_assets	bool	Whether also alarms for related source assets should be included. Requires source.	None
with_source_devices	bool	Whether also alarms for related source devices should be included. Requires source	None
limit	int	Limit the number of results to this number.	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Define the number of events which are read (and parsed in one chunk). This is a performance related setting.	1000
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None
as_values	str | tuple | list[str | tuple]	(*str|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	None

Returns:

Type	Description
Generator[Event]	Generator for Event objects

See also

https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language

update(*events: Event)

Write changes to the database.

Parameters:

Name	Type	Description	Default
*events	Event	Collection of Event instances	()

update_attachment(event_id: str, file: str | BinaryIO, content_type: str = None) -> dict

Update an event's binary attachment.

Parameters:

Name	Type	Description	Default
event_id	str	The database ID of the event	required
file	str | BinaryIO	File-like object or a file path	required
content_type	str	Content type of the file sent (default is application/octet-stream)	None

Returns:

Type	Description
dict	Attachment details as JSON object (dict).

Alarms

A wrapper for the standard Alarms API.

This class can be used for get, search for, create, update and delete alarms within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Alarms

apply_by(alarm: Alarm, expression: str = None, type: str = None, source: str = None, fragment: str = None, status: str = None, severity: str = None, resolved: str = None, date_from: str | datetime = None, date_to: str | datetime = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, with_source_assets: bool = None, with_source_devices: bool = None, **kwargs)

Apply changes made to a single instance to other objects in the database.

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
alarm	Alarm	Object serving as model for the update	required
type	str	Alarm type	None
source	str	Database ID of a source device	None
fragment	str	Name of a present custom/standard fragment	None
status	str	Alarm status	None
severity	str	Alarm severity	None
resolved	str	Whether the alarm status is CLEARED	None
before	str | datetime	Datetime object or ISO date/time string. Only alarms assigned to a time before this date are returned.	None
after	str | datetime	Datetime object or ISO date/time string. Only alarms assigned to a time after this date are returned	None
date_from	str | datetime	Same as after	None
date_to	str | datetime	Same as before	None
min_age	timedelta	Matches only alarms of at least this age	None
max_age	timedelta	Matches only alarms with at most this age	None
with_source_assets	bool	Whether also alarms for related source assets should be included. Requires source.	None
with_source_devices	bool	Whether also alarms for related source devices should be included. Requires source	None

See also: https://cumulocity.com/api/#operation/putAlarmCollectionResource

apply_to(alarm: Alarm | dict, *alarm_ids: str)

Apply changes made to a single instance to other objects in the database.

Parameters:

Name	Type	Description	Default
alarm	Alarm | dict	Object serving as model for the update or simply a dictionary representing the diff JSON.	required
*alarm_ids	str	A collection of database IDS of alarms	()

count(expression: str = None, type: str = None, source: str = None, fragment: str = None, status: str = None, severity: str = None, resolved: str = None, date_from: str | datetime = None, date_to: str | datetime = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, with_source_assets: bool = None, with_source_devices: bool = None, **kwargs) -> int

Count the number of certain alarms.

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
type	str	Alarm type	None
source	str	Database ID of a source device	None
fragment	str	Name of a present custom/standard fragment	None
status	str	Alarm status	None
severity	str	Alarm severity	None
resolved	str	Whether the alarm status is CLEARED	None
before	str | datetime	Datetime object or ISO date/time string. Only alarms assigned to a time before this date are returned.	None
after	str | datetime	Datetime object or ISO date/time string. Only alarms assigned to a time after this date are returned	None
date_from	str | datetime	Same as after	None
date_to	str | datetime	Same as before	None
min_age	timedelta	Matches only alarms of at least this age	None
max_age	timedelta	Matches only alarms with at most this age	None
with_source_assets	bool	Whether also alarms for related source assets should be included. Requires source.	None
with_source_devices	bool	Whether also alarms for related source devices should be included. Requires source	None

Returns:

Type	Description
int	Number of matching alarms in Cumulocity.

create(*alarms)

Create alarm objects within the database.

Parameters:

Name	Type	Description	Default
*alarms	Alarm	Collection of Alarm instances	()

delete(*alarms) -> None

Delete alarm objects within the database.

Note: within Cumulocity alarms are identified by type and source. These fields must be defined within the provided objects for this operation to function.

Parameters:

Name	Type	Description	Default
*alarms	Alarm	Collection of Alarm instances.	()

delete_by(expression: str = None, type: str = None, source: str = None, fragment: str = None, status: str = None, severity: str = None, resolved: str = None, date_from: str | datetime = None, date_to: str | datetime = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, with_source_assets: bool = None, with_source_devices: bool = None, **kwargs)

Query the database and delete matching alarms.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (as defined in the Cumulocity REST API).

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
type	str	Alarm type	None
source	str	Database ID of a source device	None
fragment	str	Name of a present custom/standard fragment	None
status	str	Alarm status	None
severity	str	Alarm severity	None
resolved	str	Whether the alarm status is CLEARED	None
before	str | datetime	Datetime object or ISO date/time string. Only alarms assigned to a time before this date are returned.	None
after	str | datetime	Datetime object or ISO date/time string. Only alarms assigned to a time after this date are returned	None
date_from	str | datetime	Same as after	None
date_to	str | datetime	Same as before	None
min_age	timedelta	Matches only alarms of at least this age	None
max_age	timedelta	Matches only alarms with at most this age	None
with_source_assets	bool	Whether also alarms for related source assets should be included. Requires source.	None
with_source_devices	bool	Whether also alarms for related source devices should be included. Requires source	None

get(id: str) -> Alarm

Retrieve a specific object from the database.

Parameters:

Name	Type	Description	Default
id	str	The database ID of the object	required

Returns:

Type	Description
Alarm	An Alarm instance representing the object in the database.

get_all(expression: str = None, type: str = None, source: str = None, fragment: str = None, status: str = None, severity: str = None, resolved: str = None, before: str | datetime = None, after: str | datetime = None, date_from: str | datetime = None, date_to: str | datetime = None, created_before: str | datetime = None, created_after: str | datetime = None, created_from: str | datetime = None, created_to: str | datetime = None, updated_before: str | datetime = None, updated_after: str | datetime = None, last_updated_from: str | datetime = None, last_updated_to: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, with_source_assets: bool = None, with_source_devices: bool = None, reverse: bool = False, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> List[Alarm]

Query the database for alarms and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

See select for a documentation of arguments.

Returns:

Type	Description
List[Alarm]	List of Alarm objects

select(expression: str = None, type: str = None, source: str = None, fragment: str = None, status: str = None, severity: str = None, resolved: str = None, before: str | datetime = None, after: str | datetime = None, date_from: str | datetime = None, date_to: str | datetime = None, created_before: str | datetime = None, created_after: str | datetime = None, created_from: str | datetime = None, created_to: str | datetime = None, updated_before: str | datetime = None, updated_after: str | datetime = None, last_updated_from: str | datetime = None, last_updated_to: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, with_source_assets: bool = None, with_source_devices: bool = None, reverse: bool = False, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> Generator[Alarm]

Query the database for alarms and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (as defined in the Cumulocity REST API).

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
type	str	Alarm type	None
source	str	Database ID of a source device	None
fragment	str	Name of a present custom/standard fragment	None
status	str	Alarm status	None
severity	str	Alarm severity	None
resolved	str	Whether the alarm status is CLEARED	None
before	str | datetime	Datetime object or ISO date/time string. Only alarms assigned to a time before this date are returned.	None
after	str | datetime	Datetime object or ISO date/time string. Only alarms assigned to a time after this date are returned	None
created_before	str | datetime	Datetime object or ISO date/time string. Only alarms changed at a time before this date are returned.	None
created_after	str | datetime	Datetime object or ISO date/time string. Only alarms changed at a time after this date are returned.	None
updated_before	str | datetime	Datetime object or ISO date/time string. Only alarms changed at a time before this date are returned.	None
updated_after	str | datetime	Datetime object or ISO date/time string. Only alarms changed at a time after this date are returned.	None
min_age	timedelta	Matches only alarms of at least this age	None
max_age	timedelta	Matches only alarms with at most this age	None
date_from	str | datetime	Same as after	None
date_to	str | datetime	Same as before	None
created_from	str | datetime	Same as created_after	None
created_to	str | datetime	Same as created_before	None
last_updated_from	str | datetime	Same as updated_after	None
last_updated_to	str | datetime	Same as updated_before	None
with_source_assets	bool	Whether also alarms for related source assets should be included. Requires source.	None
with_source_devices	bool	Whether also alarms for related source devices should be included. Requires source	None
reverse	bool	Invert the order of results, starting with the most recent one	False
limit	int	Limit the number of results to this number.	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Define the number of alarms which are read (and parsed in one chunk). This is a performance related setting.	1000
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None
as_values	str | tuple | list[str | tuple]	(*str|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	None

Returns:

Type	Description
Generator[Alarm]	Generator of Alarm objects

See also

https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language

update(*alarms)

Write changes to the database.

Parameters:

Name	Type	Description	Default
*alarms	Alarm	Collection of Alarm instances	()

Users

Provides access to the User API.

See also: https://cumulocity.com/api/core/#tag/Users

create(*users)

Create users within the database.

Parameters:

Name	Type	Description	Default
*users	User	Collection of User instances	()

get(username: str)

Retrieve a specific user.

Parameters:

Name	Type	Description	Default
username	str	The ID of the user (usually the mail address)	required

Returns:

Type	Description
	A User instance

get_all(username: str = None, groups: str | int | GlobalRole | List[str] | List[int] | List[GlobalRole] = None, owner: str = None, only_devices: bool = None, with_subusers_count: bool = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> list[User]

Select and retrieve User instances as list.

The result can be limited by username (prefix) and/or group membership.

See select for a documentation of arguments.

Returns:

Type	Description
list[User]	List of User instances

get_current() -> CurrentUser

Retrieve current user.

Returns:

Type	Description
CurrentUser	CurrentUser instance

get_tfa_settings(user_id: str) -> TfaSettings

Read the TFA settings of a given user.

Parameters:

Name	Type	Description	Default
user_id	str	The user to query the settings for	required

Returns:

Type	Description
TfaSettings	A TfaSettings object

logout_all()

Terminate all user's sessions.

revoke_totp_secret(user_id: str)

Revoke the currently set TFA/TOTP secret for a user.

Parameters:

Name	Type	Description	Default
user_id	str	The user to set an owner for	required

select(expression: str = None, username: str = None, groups: str | int | GlobalRole | List[str] | List[int] | List[GlobalRole] = None, owner: str = None, only_devices: bool = None, with_subusers_count: bool = None, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 5, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> Generator[User]

Lazily select and yield User instances.

The result can be limited by username (prefix) and/or group membership.

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
username	str	A user's username or a prefix thereof	None
groups	(int, [int], str, [str], GlobalRole, [GlobalRole])	a scalar or list of int (actual group ID), string (group names), or actual Group instances	None
owner	str	Username of the owner of the user	None
only_devices	bool	Only return device users (starting with device_) If absent or False, the users will be excluded.	None
with_subusers_count	bool	Whether to include an additional field subusersCount which holds the number of direct sub users.	None
limit	int	Limit the number of results to this number.	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Define the number of events which are read (and parsed in one chunk). This is a performance related setting.	5
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None
as_values	str | tuple | list[str | tuple]	(*str|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	None

Returns:

Type	Description
Generator[User]	Generator of User instances

See also

https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language

set_current_password(current_password: str, new_password: str)

Set the password of the current user.

Note: This automatically updates the connection with the new auth information.

Parameters:

Name	Type	Description	Default
current_password	str	The current password	required
new_password	str	The new password to set	required

set_delegate(user_id: str, delegate_id: str | None)

Set the delegate of a given user.

Parameters:

Name	Type	Description	Default
user_id	str	The user to set an owner for	required
delegate_id	str	The ID of the delegate user; Can be None to unassign/remove the current owner	required

set_owner(user_id: str, owner_id: str | None)

Set the owner of a given user.

Parameters:

Name	Type	Description	Default
user_id	str	The user to set an owner for	required
owner_id	str	The ID of the owner user; Can be None to unassign/remove the current owner	required

GlobalRoles

Provides access to the Global Role API.

Notes

• Global Roles are called 'groups' in the Cumulocity Standard REST API; However, 'global roles' is the official concept name and therefore used for consistency with the Cumulocity realm.

See also: https://cumulocity.com/api/core/#tag/Groups

assign_permissions(role_id: int | str, *permissions: str)

Add permissions to a global role.

Parameters:

Name	Type	Description	Default
role_id	int | str	Technical ID of the global role	required
*permissions	str	Iterable of permission ID to assign	()

assign_users(role_id: int | str, *usernames: str)

Add users to a global role.

Parameters:

Name	Type	Description	Default
role_id	int | str	Technical ID of the global role	required
*usernames	str	Iterable of usernames to assign	()

get(role_id: int | str) -> GlobalRole

Retrieve a specific global role.

Note: The C8Y REST API does not support direct query by name. Hence, searching by name will actually retrieve all available groups and return the matching ones. These groups will be cached internally for subsequent calls.

See also method reset_caches

Parameters:

Name	Type	Description	Default
role_id	int | str	An actual global role ID as int/string or a global role name	required

Returns:

Type	Description
GlobalRole	A GlobalRole instance for the ID/name.

get_all(username: str = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000) -> List[GlobalRole]

Retrieve global roles.

Parameters:

Name	Type	Description	Default
username	str	Retrieve global roles assigned to a specified user If omitted, all available global roles are returned	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Maximum number of entries fetched per requests; this is a performance setting	1000

Return

List of GlobalRole instances

See also

https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language

reset_caches()

Reset internal caching.

Caches are used for lookups of global roles by name.

select(username: str = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 5) -> Generator[GlobalRole]

Iterate over global roles.

Parameters:

Name	Type	Description	Default
username	str	Retrieve global roles assigned to a specified user If omitted, all available global roles are returned	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Maximum number of entries fetched per requests; this is a performance setting	5

Return

Generator of GlobalRole instances

See also

https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language

unassign_permissions(role_id: int | str, *permissions: str)

Remove permissions from a global role.

Parameters:

Name	Type	Description	Default
role_id	int | str	Technical ID of the global role	required
*permissions	str	Iterable of permission ID to assign	()

unassign_users(role_id: int | str, *usernames: str)

Remove users from a global role.

Parameters:

Name	Type	Description	Default
role_id	int | str	Technical ID of the global role	required
*usernames	str	Iterable of usernames to unassign	()

InventoryRoles

Provides access to the InventoryRole API.

This class can be used for get, search for, create, update and delete inventory roles within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Inventory-Roles

create(*roles: InventoryRole)

Create objects within the database.

Parameters:

Name	Type	Description	Default
*roles	InventoryRole	Collection of InventoryRole instances	()

get(role_id: str | int) -> InventoryRole

Get a specific inventory role object.

Parameters:

Name	Type	Description	Default
role_id	str | int	Cumulocity ID of the inventory role	required

Returns:

Type	Description
InventoryRole	An InventoryRole instance for this ID

Raises:

Type	Description
SyntaxError	if the ID is not defined.

Note: In contrast to other API the InventoryRole API does not raise an KeyError (i.e. 404) for undefined ID but a SyntaxError (HTTP 500).

get_all(limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None) -> List[InventoryRole]

Get all defined inventory roles.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

See select for a documentation of arguments.

Returns:

Type	Description
List[InventoryRole]	List of InventoryRole objects

get_all_assignments(username: str) -> List[InventoryRoleAssignment]

Get all inventory role assignments of a user.

This function is a greedy version of the select_assignments function. All available results are read immediately and returned as list.

See select_assignments for a documentation of arguments.

Returns:

Type	Description
List[InventoryRoleAssignment]	List of InventoryRoleAssignment objects

select(limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None) -> Generator[InventoryRole]

Get all defined inventory roles.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

Note: The InventoryRole API does not support filters.

Parameters:

Name	Type	Description	Default
limit	int	Limit the number of results to this number.	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Define the number of objects read (and parsed in one chunk). This is a performance related setting.	1000
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None

Returns:

Type	Description
Generator[InventoryRole]	Generator for InventoryRole objects

See also

https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language

select_assignments(username: str) -> Generator[InventoryRoleAssignment]

Get all inventory role assignments of a user.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

Parameters:

Name	Type	Description	Default
username	str	Username of a Cumulocity user	required

Returns:

Type	Description
Generator[InventoryRoleAssignment]	Generator for InventoryRoleAssignment objects

update(*roles: InventoryRole)

Write changes to the database.

Parameters:

Name	Type	Description	Default
*roles	InventoryRole	Collection of InventoryRole instances	()

Subscriptions

Provides access to the Notification 2.0 Subscriptions API.

This class can be used for get, search for, create, and delete Notification2 subscriptions within the Cumulocity database.

https://cumulocity.com/api/core/#tag/Subscriptions

https://cumulocity.com/guides/reference/notifications/

create(*subscriptions: Subscription) -> None

Create subscriptions within the database.

Parameters:

Name	Type	Description	Default
*subscriptions	TenantOption	Collection of Subscription instances	()

delete_by(context: str = None, source: str = None) -> None

Delete subscriptions within the database.

Parameters:

Name	Type	Description	Default
context	str	Subscription context	None
source	str	Managed object ID the subscription is for.	None

get(subscription_id: str) -> Subscription

Retrieve a specific subscription from the database.

Parameters:

Name	Type	Description	Default
subscription_id	str	Subscription ID	required

Returns:

Type	Description
Subscription	A Subscription instance

Raises:

Type	Description
KeyError	if the given ID is not defined within the database

get_all(expression: str = None, context: str = None, source: str = None, subscription: str = None, type_filter: str = None, limit: int = None, page_size: int = 1000, page_number: int = None, **kwargs) -> List[Subscription]

Query the database for subscriptions and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

Returns:

Type	Description
List[Subscription]	List of Subscription instances.

get_count(expression: str = None, context: str = None, source: str = None, subscription: str = None, type_filter: str = None, **kwargs) -> int

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
int	Number of potential results

select(expression: str = None, context: str = None, source: str = None, subscription: str = None, type_filter: str = None, limit: int = None, page_size: int = 1000, page_number: int = None, **kwargs) -> Generator[Subscription]

Query the database for subscriptions and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters' specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
context	str	Subscription context.	None
source	str	Managed object ID the subscription is for.	None
subscription	str	The subscription name.	None
type_filter	str	The type to filter subscriptions	None
limit	int	Limit the number of results to this number.	None
page_size	int	Define the number of objects which are read (and parsed in one chunk). This is a performance related setting.	1000
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None

Returns:

Type	Description
Generator[Subscription]	Generator for Subscription instances

Tokens

Provides access to the Notification 2.0 token generation API.

This class can be used for get, search for, create, and delete Notification2 subscriptions within the Cumulocity database.

https://cumulocity.com/api/core/#tag/Tokens

https://cumulocity.com/guides/reference/notifications/

build_websocket_uri(token: str, consumer: str = None)

Build websocket access URL.

Parameters:

Name	Type	Description	Default
token	str	Subscriber access token	required
consumer	str	Optional consumer ID (to allow 'sticky' connections after interrupt).	None

Returns:

Type	Description
	A websocket (ws(s)://) URL to access the subscriber channel.

generate(subscription: str, expires: int = 1440, subscriber: str = None, signed: bool = None, shared: bool = None, non_persistent: bool = None) -> str

Generate a new access token.

Parameters:

Name	Type	Description	Default
subscription	str	Subscription name.	required
expires	int	Expiration time in minutes.	1440
subscriber	str	Subscriber ID (name). A UUID based default will be used if None.	None
signed	bool	Whether the token should be signed.	None
shared	bool	Whether the token is used to create a shared consumer.	None
non_persistent	bool	Whether the token refers to the non-persistent variant of the named subscription.	None

Returns:

Type	Description
str	JWT access token as string.

renew(token: str) -> str

Renew a token.

Parameters:

Name	Type	Description	Default
token	str	Token to be renewed.	required

unsubscribe(token: str)

Invalidate a token and unsubscribe a subscriber.

Parameters:

Name	Type	Description	Default
token	str	Subscribed token	required

Operations

A wrapper for the standard Operation API.

This class can be used for get, search for, create, update and delete operations within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Operations

delete_by(expression: str = None, agent_id: str = None, device_id: str = None, status: str = None, bulk_id: str = None, fragment: str = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, **kwargs)

Query the database and delete matching operations.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (as defined in the Cumulocity REST API).

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
agent_id	str	Database ID of agent	None
device_id	str	Database ID of device	None
status	str	Status of operation	None
bulk_id	str	The bulk operation ID that this object belongs to	None
fragment	str	Name of a present custom/standard fragment	None
before	datetime | str	Datetime object or ISO date/time string. Only operations assigned to a time before this date are selected.	None
after	datetime | str	Datetime object or ISO date/time string. Only operation assigned to a time after this date are selected.	None
min_age	timedelta	Timedelta object. Only operation of at least this age are returned.	None
max_age	timedelta	Timedelta object. Only operations with at most this age are returned. build a base query	None

get(operation_id: str | int) -> Operation

Read a specific operation from the database.

Parameters:

Name	Type	Description	Default
operation_id	str | int	database ID of an operation	required

Returns:

Type	Description
Operation	Operation object

Raises:

Type	Description
KeyError	if the ID cannot be resolved.

get_all(expression: str = None, agent_id: str = None, device_id: str = None, status: str = None, bulk_id: str = None, fragment: str = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, date_from: str | datetime = None, date_to: str | datetime = None, reverse: bool = False, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> List[Operation]

Query the database for operations and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

Returns:

Type	Description
List[Operation]	List of matching Operation objects

get_count(expression: str = None, agent_id: str = None, device_id: str = None, status: str = None, bulk_id: str = None, fragment: str = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, date_from: str | datetime = None, date_to: str | datetime = None, **kwargs) -> int

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
int	Number of potential results

get_last(expression: str = None, agent_id: str = None, device_id: str = None, status: str = None, bulk_id: str = None, fragment: str = None, date_to: str | datetime = None, before: str | datetime = None, min_age: timedelta = None, **kwargs) -> Operation | None

Query the database and return the last matching operation.

This function is a special variant of the select function. Only the last matching result is returned.

Returns:

Type	Description
Operation | None	Last matching Operation object or None

select(expression: str = None, agent_id: str = None, device_id: str = None, status: str = None, bulk_id: str = None, fragment: str = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, date_from: str | datetime = None, date_to: str | datetime = None, reverse: bool = False, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> Generator[Operation]

Query the database for operations and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
agent_id	str	Database ID of agent	None
device_id	str	Database ID of device	None
status	str	Status of operation	None
bulk_id	str	The bulk operation ID that this object belongs to	None
fragment	str	Name of a present custom/standard fragment	None
before	datetime | str	Datetime object or ISO date/time string. Only operations assigned to a time before this date are returned.	None
after	datetime | str	Datetime object or ISO date/time string. Only operations assigned to a time after this date are returned.	None
min_age	timedelta	Timedelta object. Only operation of at least this age are returned.	None
max_age	timedelta	Timedelta object. Only operations with at most this age are returned.	None
date_from	str | datetime	Same as after	None
date_to	str | datetime	Same as before	None
reverse	bool	Invert the order of results, starting with the most recent one.	False
limit	int	Limit the number of results to this number.	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Define the number of operations which are read (and parsed in one chunk). This is a performance related setting.	1000
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None
as_values	str | tuple | list[str | tuple]	(*str|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	None

Returns:

Type	Description
Generator[Operation]	Generator[Operation]: Iterable of matching Operation objects

See also

https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language

BulkOperations

A wrapper for the standard Bulk Operation API.

This class can be used for get, search for, create, update and delete bulk operations within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Bulk-operations

get(operation_id: str | int) -> BulkOperation

Read a specific bulk operation from the database.

Parameters:

Name	Type	Description	Default
operation_id	str | int	database ID of a bulk operation	required

Returns:

Type	Description
BulkOperation	BulkOperation object

Raises:

Type	Description
KeyError	if the ID cannot be resolved.

get_all(limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, **kwargs) -> List[BulkOperation]

Query the database for bulk operations and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

Returns:

Type	Description
List[BulkOperation]	List of matching BulkOperation objects

get_count(**kwargs) -> int

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
int	Number of potential results

select(limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, **kwargs) -> Generator[BulkOperation]

Query the database for operations and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters' specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
limit	int	Limit the number of results to this number.	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Define the number of operations which are read (and parsed in one chunk). This is a performance related setting.	1000
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None

Returns:

Type	Description
Generator[BulkOperation]	Generator[BulkOperation]: Iterable of matching BulkOperation objects

Applications

Provides access to the Application API.

This class can be used for get, search for, create, update and delete applications within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Application-API

get(application_id: str) -> Application

Retrieve a specific object from the database.

Parameters:

Name	Type	Description	Default
application_id	str	The database ID of the application	required

Returns:

Type	Description
Application	An Application instance representing the object in the database.

get_all(expression: str = None, name: str = None, type: str = None, owner: str = None, user: str = None, tenant: str = None, subscriber: str = None, provided_for: str = None, has_versions: bool = None, limit: int = None, page_size: int = 100, page_number: int = None, **kwargs) -> List[Application]

Query the database for applications and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

See select for a documentation of arguments.

Returns:

Type	Description
List[Application]	List of Application objects

get_current() -> Application

Retrieve the current application.

Note: Requires boostrap permissions.

Returns:

Type	Description
Application	An Application instance.

get_current_settings() -> List[ApplicationSetting]

Query the database for the current application's settings.

Note: Requires boostrap permissions.

Returns:

Type	Description
List[ApplicationSetting]	List of ApplicationSetting instances.

get_current_subscriptions() -> List[ApplicationSubscription]

Query the database for subscriptions of the current application.

Note: Requires boostrap permissions.

Returns:

Type	Description
List[ApplicationSubscription]	List of ApplicationSubscription instances.

select(expression: str = None, name: str = None, type: str = None, owner: str = None, user: str = None, tenant: str = None, subscriber: str = None, provided_for: str = None, has_versions: bool = None, limit: int = None, page_size: int = 100, page_number: int = None, **kwargs) -> Generator[Application]

Query the database for applications and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters' specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
name	str	Name of an application (no wildcards allowed)	None
type	str	Application type (e.g. HOSTED)	None
owner	str	ID of a Cumulocity user which owns the application	None
user	str	ID of a Cumulocity user which has general access	None
tenant	str	ID of a Cumulocity tenant which either owns the application or is subscribed to it	None
subscriber	str	ID of a Cumulocity tenant which is subscribed to the application (and may own it)	None
provided_for	str	ID of a Cumulocity tenant which is subscribed to the application but does not own it	None
has_versions	bool	Whether to filter for applications with a defined applicationVersions field	None
limit	int	Limit the number of results to this number.	None
page_size	int	Define the number of events which are read (and parsed in one chunk). This is a performance related setting.	100
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None

Returns:

Type	Description
Generator[Application]	A Generator for Application objects.

upload_attachment(application_id: str, file: str | BinaryIO)

Upload application binary for a registered application.

Parameters:

Name	Type	Description	Default
application_id	str	The Cumulocity object ID of the application	required
file	str | BinaryIO	File path or file-like object to upload.	required

See also: https://cumulocity.com/api/core/#tag/Application-binaries

TenantOptions

Provides access to the Tenant Options API.

This class can be used for get, search for, create, update and delete tenant options within the Cumulocity database.

See also: https://cumulocity.com/api/latest/#tag/Options

build_object_path(category: str, key: str) -> str

Build the path to a specific object of this resource.

Note: this function overrides with different arguments because tenant options, unlike other objects, are not identified by ID but category/key.

Parameters:

Name	Type	Description	Default
category	str	Option category	required
key	str	Option key (name)	required

Returns:

Type	Description
str	The relative path to the object within Cumulocity.

create(*options: TenantOption) -> None

Create options within the database.

Parameters:

Name	Type	Description	Default
*options	TenantOption	Collection of TenantObject instances	()

delete(*options: TenantOption) -> None

Delete options within the database.

Parameters:

Name	Type	Description	Default
*options	TenantOption	Collection of TenantObject instances	()

delete_by(category: str, key: str) -> None

Delete specific option within the database.

Parameters:

Name	Type	Description	Default
category	str	Option category	required
key	str	Option key (name)	required

get(category: str, key: str) -> TenantOption

Retrieve a specific option from the database.

Parameters:

Name	Type	Description	Default
category	str	Option category	required
key	str	Option key (name)	required

Returns:

Type	Description
TenantOption	A TenantOption instance

Raises:

Type	Description
KeyError	if the given combination of category and key is not defined within the database

get_all(category: str = None, limit: int = None, page_size: int = 1000, page_number: int = None) -> List[TenantOption]

Query the database for tenant options and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

Returns:

Type	Description
List[TenantOption]	List of TenantObject instances

get_all_mapped(category: str = None) -> Dict[str, str]

Query the database for tenant options and return the results as a dictionary.

This result dictionary does not specify option categories hence it is best used with the category filter unless the keys are unique by themselves.

Parameters:

Name	Type	Description	Default
category	str	Option category	None

Returns:

Type	Description
Dict[str, str]	Dictionary of option keys to values.

get_value(category: str, key: str) -> str

Retrieve the value of a specific option from the database.

Parameters:

Name	Type	Description	Default
category	str	Option category	required
key	str	Option key (name)	required

Returns:

Type	Description
str	The value of the specified option

Raises:

Type	Description
KeyError	if the given combination of category and key is not defined within the database

select(category: str = None, limit: int = None, page_size: int = 1000, page_number: int = None) -> Generator[TenantOption]

Query the database for tenant options and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
category	str	Option category	None
limit	int	Limit the number of results to this number.	None
page_size	int	Define the number of objects which are read (and parsed in one chunk). This is a performance related setting.	1000
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None

Returns:

Type	Description
Generator[TenantOption]	Generator for TenantObject instances

set_value(category: str, key: str, value: str)

Create an option within the database.

This is a shortcut function to avoid unnecessary instantiation of the TenantOption class.

Parameters:

Name	Type	Description	Default
category	str	Option category	required
key	str	Option key (name)	required
value	str	Option value	required

update(*options: TenantOption) -> None

Update options within the database.

Parameters:

Name	Type	Description	Default
*options	TenantOption	Collection of TenantObject instances	()

update_by(category: str, options: Dict[str, str]) -> None

Update options within the database.

Parameters:

Name	Type	Description	Default
category	str	Option category	required
options	dict	A dictionary of option keys and values	required

AuditRecords

Provides access to the Audit API.

This class can be used for get, search for, create, update and delete records within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Audits

create(*records: AuditRecord)

Create audit record objects within the database.

If not yet defined, this will set the record date to now in

each of the given objects.

Parameters:

Name	Type	Description	Default
*records	AuditRecord	Collection of AuditRecord instances	()

get(record_id: str) -> AuditRecord

Retrieve a specific object from the database.

Parameters:

Name	Type	Description	Default
record_id	str	The database ID of the audit record	required

Returns:

Type	Description
AuditRecord	An AuditRecord instance representing the object in the database.

get_all(expression: str = None, type: str = None, source: str = None, application: str = None, user: str = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, reverse: bool = False, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> List[AuditRecord]

Query the database for audit records and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

See select for a documentation of arguments.

Returns:

Type	Description
List[AuditRecord]	List of AuditRecord objects

select(expression: str = None, type: str = None, source: str = None, application: str = None, user: str = None, before: str | datetime = None, after: str | datetime = None, min_age: timedelta = None, max_age: timedelta = None, reverse: bool = False, limit: int = None, include: str | JsonMatcher = None, exclude: str | JsonMatcher = None, page_size: int = 1000, page_number: int = None, as_values: str | tuple | list[str | tuple] = None, **kwargs) -> Generator[AuditRecord]

Query the database for audit records and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters' specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
type	str	Audit record type	None
source	str	Database ID of a source device	None
application	str	Application from which the audit was carried out.	None
user	str	The user who carried out the activity.	None
before	str | datetime	Datetime object or ISO date/time string. Only records assigned to a time before this date are returned.	None
after	str | datetime	Datetime object or ISO date/time string. Only records assigned to a time after this date are returned.	None
min_age	timedelta	Minimum age for selected records.	None
max_age	timedelta	Maximum age for selected records.	None
reverse	bool	Invert the order of results, starting with the most recent one.	False
limit	int	Limit the number of results to this number.	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
page_size	int	Define the number of objects which are read (and parsed in one chunk). This is a performance related setting.	1000
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None
as_values	str | tuple | list[str | tuple]	(*str|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	None

Returns:

Type	Description
Generator[AuditRecord]	Generator for AuditRecord objects

See also

https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language