Functions

Functions API

`AsyncCogniteClient.functions.activate`()	Activate functions for the Project.
`AsyncCogniteClient.functions.call`([id, ...])	Call a function by its ID or external ID.
`AsyncCogniteClient.functions.create`(name[, ...])	When creating a function, the source code can be specified in one of three ways:
`AsyncCogniteClient.functions.delete`([id, ...])	Delete one or more functions.
`AsyncCogniteClient.functions.limits`()	Get service limits.
`AsyncCogniteClient.functions.list`([name, ...])	List all functions.
`AsyncCogniteClient.functions.retrieve`([id, ...])	Retrieve a single function by id.
`AsyncCogniteClient.functions.retrieve_multiple`([...])	Retrieve multiple functions by id.
`AsyncCogniteClient.functions.status`()	Functions activation status for the Project.

Function calls

`AsyncCogniteClient.functions.calls.get_logs`(call_id)	Retrieve logs for function call.
`AsyncCogniteClient.functions.calls.get_response`(call_id)	Retrieve the response from a function call.
`AsyncCogniteClient.functions.calls.list`([...])	List all calls associated with a specific function id.
`AsyncCogniteClient.functions.calls.retrieve`(call_id)	Retrieve a single function call by id.

Function schedules

`AsyncCogniteClient.functions.schedules.create`(name)	Create a schedule associated with a specific project.
`AsyncCogniteClient.functions.schedules.delete`(id)	Delete a schedule associated with a specific project.
`AsyncCogniteClient.functions.schedules.get_input_data`(id)	Retrieve the input data to the associated function.
`AsyncCogniteClient.functions.schedules.list`([...])	List all schedules associated with a specific project.
`AsyncCogniteClient.functions.schedules.retrieve`(id)	Retrieve a single function schedule by id.

Data classes

class cognite.client.data_classes.functions.Function( id: int, created_time: int, name: str, status: str, file_id: int, external_id: str | None = None, description: str | None = None, owner: str | None = None, function_path: str = 'handler.py', secrets: dict[str, str] | None = None, env_vars: dict[str, str] | None = None, cpu: float | None = None, memory: float | None = None, runtime: Literal['py310', 'py311', 'py312', 'py313'] | None = None, runtime_version: str | None = None, metadata: dict[str, str] | None = None, error: dict | None = None, last_called: int | None = None, )

Bases: FunctionCore

A representation of a Cognite Function. This is the read version, which is used when retrieving a function.

Parameters:

id (int) – ID of the function.
created_time (int) – Created time in UNIX.
name (str) – Name of the function.
status (str) – Status of the function.
file_id (int) – File id of the code represented by this object.
external_id (str | None) – External id of the function.
description (str | None) – Description of the function.
owner (str | None) – Owner of the function.
function_path (str) – Relative path from the root folder to the file containing the handle function. Defaults to handler.py. Must be on posix path format.
secrets (dict[str, str] | None) – Secrets attached to the function ((key, value) pairs).
env_vars (dict[str, str] | None) – User specified environment variables on the function ((key, value) pairs).
cpu (float | None) – Number of CPU cores per function. Allowed range and default value are given by the limits endpoint., and None translates to the API default. On Azure, only the default value is used.
memory (float | None) –
Memory per function measured in GB. Allowed range and default value are given by the limits endpoint., and None translates to the API default. On Azure, only the default value is used.
runtime (RunTime | None) – Runtime of the function. Allowed values are [“py310”, “py311”, “py312”, “py313”]. The runtime “py313” resolves to the latest version of the Python 3.13 series.
runtime_version (str | None) – The complete specification of the function runtime with major, minor and patch version numbers.
metadata (dict[str, str] | None) – Metadata associated with a function as a set of key:value pairs.
error (dict | None) – Dictionary with keys “message” and “trace”, which is populated if deployment fails.
last_called (int | None) – Last time the function was called, in UNIX timestamp milliseconds.

as_write() → FunctionWrite: Returns a writeable version of this function.

call( data: dict[str, object] | None = None, wait: bool = True, ) → FunctionCall

Call this particular function.

Parameters:

data (dict[str, object] | None) – Input data to the function (JSON serializable). This data is passed deserialized into the function through one of the arguments called data. WARNING: Secrets or other confidential information should not be passed via this argument. There is a dedicated secrets argument in FunctionsAPI.create() for this purpose.
wait (bool) – Wait until the function call is finished. Defaults to True.

Returns:

A function call object.

Return type:

FunctionCall

async call_async( data: dict[str, object] | None = None, wait: bool = True, ) → FunctionCall

Call this particular function.

Parameters:

data (dict[str, object] | None) – Input data to the function (JSON serializable). This data is passed deserialized into the function through one of the arguments called data. WARNING: Secrets or other confidential information should not be passed via this argument. There is a dedicated secrets argument in FunctionsAPI.create() for this purpose.
wait (bool) – Wait until the function call is finished. Defaults to True.

Returns:

A function call object.

Return type:

FunctionCall

List all calls to this function.

Parameters:

status (str | None) – Status of the call. Possible values [“Running”, “Failed”, “Completed”, “Timeout”].
schedule_id (int | None) – Schedule id from which the call belongs (if any).
start_time (dict[str, int] | None) – Start time of the call. Possible keys are min and max, with values given as time stamps in ms.
end_time (dict[str, int] | None) – End time of the call. Possible keys are min and max, with values given as time stamps in ms.
limit (int | None) – Maximum number of function calls to list. Pass in -1, float(‘inf’) or None to list all Function Calls.

Returns:

List of function calls

Return type:

FunctionCallList

List all calls to this function.

Parameters:

status (str | None) – Status of the call. Possible values [“Running”, “Failed”, “Completed”, “Timeout”].
schedule_id (int | None) – Schedule id from which the call belongs (if any).
start_time (dict[str, int] | None) – Start time of the call. Possible keys are min and max, with values given as time stamps in ms.
end_time (dict[str, int] | None) – End time of the call. Possible keys are min and max, with values given as time stamps in ms.
limit (int | None) – Maximum number of function calls to list. Pass in -1, float(‘inf’) or None to list all Function Calls.

Returns:

List of function calls

Return type:

FunctionCallList

list_schedules( limit: int | None = 25, ) → FunctionSchedulesList

List all schedules associated with this function.

Parameters:: limit (int | None) – Maximum number of schedules to list. Pass in -1, float(‘inf’) or None to list all.
Returns:: List of function schedules
Return type:: FunctionSchedulesList

async list_schedules_async( limit: int | None = 25, ) → FunctionSchedulesList

List all schedules associated with this function.

Parameters:: limit (int | None) – Maximum number of schedules to list. Pass in -1, float(‘inf’) or None to list all.
Returns:: List of function schedules
Return type:: FunctionSchedulesList

retrieve_call( id: int, ) → FunctionCall | None

Retrieve call by id.

Parameters:: id (int) – ID of the call.
Returns:: Requested function call or None if not found.
Return type:: FunctionCall | None

async retrieve_call_async( id: int, ) → FunctionCall | None

Retrieve call by id.

Parameters:: id (int) – ID of the call.
Returns:: Requested function call or None if not found.
Return type:: FunctionCall | None

update() → None: Update the function object. Can be useful to check for the latest status of the function (‘Queued’, ‘Deploying’, ‘Ready’ or ‘Failed’).

async update_async() → None: Update the function object. Can be useful to check for the latest status of the function (‘Queued’, ‘Deploying’, ‘Ready’ or ‘Failed’).

class cognite.client.data_classes.functions.FunctionCall( id: int, start_time: int, status: str, function_id: int, end_time: int | None = None, scheduled_time: int | None = None, schedule_id: int | None = None, error: dict | None = None, )

Bases: CogniteResourceWithClientRef

A representation of a Cognite Function call.

Parameters:

id (int) – A server-generated ID for the object.
start_time (int) – Start time of the call, measured in number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
status (str) – Status of the function call (“Running”, “Completed” or “Failed”).
function_id (int) – No description.
end_time (int | None) – End time of the call, measured in number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
scheduled_time (int | None) – Scheduled time of the call, measured in number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
schedule_id (int | None) – The schedule id belonging to the call.
error (dict | None) – Error from the function call. It contains an error message and the stack trace.

get_logs() → FunctionCallLog

Retrieve logs for this function call.

Returns:: Log for the function call.
Return type:: FunctionCallLog

async get_logs_async() → FunctionCallLog

Retrieve logs for this function call.

Returns:: Log for the function call.
Return type:: FunctionCallLog

get_response() → dict[str, object] | None

Retrieve the response from this function call.

Returns:: Response from the function call.
Return type:: dict[str, object] | None

async get_response_async() → dict[str, object] | None

Retrieve the response from this function call.

Returns:: Response from the function call.
Return type:: dict[str, object] | None

update() → None: Update the function call object. Can be useful if the call was made with wait=False.

async update_async() → None: Update the function call object. Can be useful if the call was made with wait=False.

class cognite.client.data_classes.functions.FunctionCallList( resources: Sequence[T_CogniteResource], ): Bases: CogniteResourceList[FunctionCall], InternalIdTransformerMixin

class cognite.client.data_classes.functions.FunctionCallLog( resources: Sequence[T_CogniteResource], )

Bases: CogniteResourceList[FunctionCallLogEntry]

A collection of function call log entries.

to_text(with_timestamps: bool = False) → str

Return a new-line delimited string of the log entry messages, optionally with entry timestamps.

Parameters:: with_timestamps (bool) – Whether to include entry timestamps in the output. Defaults to False.
Returns:: new-line delimited log entries.
Return type:: str

class cognite.client.data_classes.functions.FunctionCallLogEntry(message: str, timestamp: int | None = None)

Bases: CogniteResource

A log entry for a function call.

Parameters:

message (str) – Single line from stdout / stderr.
timestamp (int | None) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

class cognite.client.data_classes.functions.FunctionCallsFilter( status: str | None = None, schedule_id: int | None = None, start_time: dict[str, int] | TimestampRange | None = None, end_time: dict[str, int] | TimestampRange | None = None, ): Bases: CogniteFilter

Bases: WriteableCogniteResourceWithClientRef[FunctionWrite], ABC

A representation of a Cognite Function.

Parameters:

name (str) – Name of the function.
external_id (str | None) – External id of the function.
description (str | None) – Description of the function.
owner (str | None) – Owner of the function.
file_id (int) – File id of the code represented by this object.
function_path (str) – Relative path from the root folder to the file containing the handle function. Defaults to handler.py. Must be on posix path format.
secrets (dict[str, str] | None) – Secrets attached to the function ((key, value) pairs).
env_vars (dict[str, str] | None) – User specified environment variables on the function ((key, value) pairs).
cpu (float | None) –
Number of CPU cores per function. Allowed range and default value are given by the limits endpoint., and None translates to the API default. On Azure, only the default value is used.
memory (float | None) –
Memory per function measured in GB. Allowed range and default value are given by the limits endpoint., and None translates to the API default. On Azure, only the default value is used.
runtime (RunTime | None) – Runtime of the function. Allowed values are [“py310”, “py311”, “py312”, “py313”]. The runtime “py313” resolves to the latest version of the Python 3.13 series.
metadata (dict[str, str] | None) – Metadata associated with a function as a set of key:value pairs.

class cognite.client.data_classes.functions.FunctionFilter( name: str | None = None, owner: str | None = None, file_id: int | None = None, status: Literal['Queued', 'Deploying', 'Ready', 'Failed'] | None = None, external_id_prefix: str | None = None, created_time: dict[Literal['min', 'max'], int] | TimestampRange | None = None, metadata: dict[str, str] | None = None, ): Bases: CogniteFilter

class cognite.client.data_classes.functions.FunctionHandle(*args, **kwargs)

Bases: Protocol

The function handle.

This is the function that will be called when the function is executed. The function must be named “handle” and can take any of the following named only arguments:

Parameters:

client (CogniteClient | None) – Cognite client.
data (dict[str, object] | None) – Input data to the function.
secrets (dict[str, str] | None) – Secrets passed to the function.
function_call_info (dict[str, object] | None) – Function call information.

Example

def handle(
    client: CogniteClient | None = None,
    data: dict[str, object] | None = None,
) -> object:
    # Do something with the data
    return {"result": "success"}

Returns:: Return value of the function. Any JSON serializable object is allowed.
Return type:: object

class cognite.client.data_classes.functions.FunctionList( resources: Sequence[T_CogniteResource], )

Bases: WriteableCogniteResourceList[FunctionWrite, Function], IdTransformerMixin

as_write() → FunctionWriteList: Returns a writeable version of this function.

class cognite.client.data_classes.functions.FunctionSchedule( id: int, name: str, created_time: int, cron_expression: str, session_id: int, when: str, function_id: int | None = None, function_external_id: str | None = None, description: str | None = None, )

Bases: FunctionScheduleCore

A representation of a Cognite Function Schedule. This is the read version, which is used when retrieving a function schedule.

Parameters:

id (int) – ID of the schedule.
name (str) – Name of the function schedule.
created_time (int) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
cron_expression (str) – Cron expression
session_id (int) – ID of the session running with the schedule.
when (str) – When the schedule will trigger, in human readable text (server generated from cron_expression).
function_id (int | None) – ID of the function.
function_external_id (str | None) – External id of the function.
description (str | None) – Description of the function schedule.

as_write() → FunctionScheduleWrite: Returns a writeable version of this function schedule.

get_input_data() → dict | None

Retrieve the input data to the associated function.

Returns:: Input data to the associated function or None if not set. This data is passed deserialized into the function through the data argument.
Return type:: dict | None

async get_input_data_async() → dict | None

Retrieve the input data to the associated function.

Returns:: Input data to the associated function or None if not set. This data is passed deserialized into the function through the data argument.
Return type:: dict | None

class cognite.client.data_classes.functions.FunctionScheduleCore( name: str, function_id: int | None, function_external_id: str | None, description: str | None, cron_expression: str, )

Bases: WriteableCogniteResourceWithClientRef[FunctionScheduleWrite], ABC

A representation of a Cognite Function Schedule.

Parameters:

name (str) – Name of the function schedule.
function_id (int | None) – Id of the function.
function_external_id (str | None) – External id of the function.
description (str | None) – Description of the function schedule.
cron_expression (str) – Cron expression

class cognite.client.data_classes.functions.FunctionScheduleWrite( name: str, cron_expression: str, function_id: int | None = None, function_external_id: str | None = None, description: str | None = None, data: dict | None = None, nonce: str | None = None, )

Bases: FunctionScheduleCore

A representation of a Cognite Function Schedule.

Parameters:

name (str) – Name of the function schedule.
cron_expression (str) – Cron expression
function_id (int | None) – ID of the function.
function_external_id (str | None) – External ID of the function.
description (str | None) – Description of the function schedule.
data (dict | None) – Input data to the function (only present if provided on the schedule). This data is passed deserialized into the function through one of the arguments called data. WARNING: Secrets or other confidential information should not be passed via the data object. There is a dedicated secrets object in the request body to “Create functions” for this purpose.
nonce (str | None) – Nonce retrieved from sessions API when creating a session. This will be used to bind the session before executing the function. The corresponding access token will be passed to the function and used to instantiate the client of the handle() function. You can create a session via the Sessions API.

as_write() → FunctionScheduleWrite: Returns this FunctionScheduleWrite instance.

class cognite.client.data_classes.functions.FunctionScheduleWriteList( resources: Sequence[T_CogniteResource], ): Bases: CogniteResourceList[FunctionScheduleWrite]

class cognite.client.data_classes.functions.FunctionSchedulesFilter( name: str | None = None, function_id: int | None = None, function_external_id: str | None = None, created_time: dict[str, int] | TimestampRange | None = None, cron_expression: str | None = None, ): Bases: CogniteFilter

class cognite.client.data_classes.functions.FunctionSchedulesList( resources: Sequence[T_CogniteResource], )

Bases: WriteableCogniteResourceList[FunctionScheduleWrite, FunctionSchedule], InternalIdTransformerMixin

as_write() → FunctionScheduleWriteList: Returns a writeable version of this function schedule.

class cognite.client.data_classes.functions.FunctionWrite( name: str, file_id: int, external_id: str | None = None, description: str | None = None, owner: str | None = None, function_path: str = 'handler.py', secrets: dict[str, str] | None = None, env_vars: dict[str, str] | None = None, cpu: float | None = None, memory: float | None = None, runtime: Literal['py310', 'py311', 'py312', 'py313'] | None = None, metadata: dict[str, str] | None = None, index_url: str | None = None, extra_index_urls: list[str] | None = None, )

Bases: FunctionCore

A representation of a Cognite Function. This is the write version, which is used when creating a function.

Parameters:

name (str) – Name of the function.
file_id (int) – File id of the code represented by this object.
external_id (str | None) – External id of the function.
description (str | None) – Description of the function.
owner (str | None) – Owner of the function.
function_path (str) – Relative path from the root folder to the file containing the handle function. Defaults to handler.py. Must be on posix path format.
secrets (dict[str, str] | None) – Secrets attached to the function ((key, value) pairs).
env_vars (dict[str, str] | None) – User specified environment variables on the function ((key, value) pairs).
cpu (float | None) –
Number of CPU cores per function. Allowed range and default value are given by the limits endpoint., and None translates to the API default. On Azure, only the default value is used.
memory (float | None) –
Memory per function measured in GB. Allowed range and default value are given by the limits endpoint., and None translates to the API default. On Azure, only the default value is used.
runtime (RunTime | None) – Runtime of the function. Allowed values are [“py310”, “py311”, “py312”, “py313”]. The runtime “py313” resolves to the latest version of the Python 3.13 series.
metadata (dict[str, str] | None) – Metadata associated with a function as a set of key:value pairs.
index_url (str | None) – Specify a different python package index, allowing for packages published in private repositories. Supports basic HTTP authentication as described in pip basic authentication. See the documentation for additional information related to the security risks of using this option.
extra_index_urls (list[str] | None) – Extra package index URLs to use when building the function, allowing for packages published in private repositories. Supports basic HTTP authentication as described in pip basic authentication. See the documentation for additional information related to the security risks of using this option.

as_write() → FunctionWrite: Returns this FunctionWrite instance.

class cognite.client.data_classes.functions.FunctionWriteList( resources: Sequence[T_CogniteResource], ): Bases: CogniteResourceList[FunctionWrite], ExternalIDTransformerMixin

class cognite.client.data_classes.functions.FunctionsLimits( timeout_minutes: int, cpu_cores: dict[str, float], memory_gb: dict[str, float], runtimes: list[Literal['py310', 'py311', 'py312', 'py313']], response_size_mb: int | None = None, )

Bases: CogniteResource

Service limits for the associated project.

Parameters:

timeout_minutes (int) – Timeout of each function call.
cpu_cores (dict[str, float]) – The number of CPU cores per function execution (i.e. function call).
memory_gb (dict[str, float]) – The amount of available memory in GB per function execution (i.e. function call).
runtimes (list[RunTime]) – Available runtimes. For example, “py313” translates to the latest version of the Python 3.13 series.
response_size_mb (int | None) – Maximum response size of function calls.

class cognite.client.data_classes.functions.FunctionsStatus(status: str)

Bases: CogniteResource

Activation Status for the associated project.

Parameters:: status (str) – Activation Status for the associated project.