Entities

Entity-related functionality is accessed through client.entities. For example:

from pyodk.client import Client

client = Client()
data = client.entities.list()

Conceptually, an Entity's parent object is an EntityList. Each EntityList may have multiple Entities. In Python parlance, EntityLists are like classes, while Entities are like instances.

create(label, data, entity_list_name=None, project_id=None, uuid=None)

Create an Entity.

Parameters:

Name	Type	Description	Default
label	str	Label of the Entity.	required
data	dict	Data to store for the Entity.	required
entity_list_name	str | None	The name of the Entity List (Dataset) being referenced.	None
project_id	int | None	The id of the project this Entity belongs to.	None
uuid	str | None	An optional unique identifier for the Entity. If not provided then a uuid will be generated and sent by the client.	None

create_many(data, entity_list_name=None, project_id=None, create_source=None, source_size=None)

Create one or more Entities in a single request.

Example input for data would be a list of dictionaries from a CSV file:

data = [ {"label": "Sydney", "state": "NSW", "postcode": "2000"}, {"label": "Melbourne", "state": "VIC", "postcode": "3000"}, ]

Each Entity in data must include a "label" key. An Entity List property must be created in advance for each key in data that is not "label". The merge method can be used to automatically add properties (or a subset) and create Entities.

Parameters:

Name	Type	Description	Default
data	Iterable[Mapping[str, Any]]	Data to store for the Entities.	required
entity_list_name	str | None	The name of the Entity List (Dataset) being referenced.	None
project_id	int | None	The id of the project this Entity belongs to.	None
create_source	str | None	Used to capture the source of the change in Central, for example a file name. Defaults to the PyODK version.	None
source_size	str | None	Used to capture the size of the source data in Central, for example a file size or row count. Excluded if None.	None

delete(uuid, entity_list_name=None, project_id=None)

Delete an Entity.

Parameters:

Name	Type	Description	Default
uuid	str	The unique identifier for the Entity.	required
entity_list_name	str | None	The name of the Entity List (Dataset) being referenced.	None
project_id	int | None	The id of the project this Entity belongs to.	None

get_table(entity_list_name=None, project_id=None, skip=None, top=None, count=None, filter=None, select=None)

Read Entity List data.

Parameters:

Name	Type	Description	Default
entity_list_name	str | None	The name of the Entity List (Dataset) being referenced.	None
project_id	int | None	The id of the project this Entity belongs to.	None
skip	int | None	The first n rows will be omitted from the results.	None
top	int | None	Only up to n rows will be returned in the results.	None
count	bool | None	If True, an @odata.count property will be added to the result to indicate the total number of rows, ignoring the above paging parameters.	None
filter	str | None	Filter responses to those matching the query. Only certain fields are available to reference. The operators lt, le, eq, neq, ge, gt, not, and, and or are supported, and the built-in functions now, year, month, day, hour, minute, second.	None
select	str | None	If provided, will return only the selected fields.	None

Returns:

Type	Description
dict	A dictionary representation of the OData JSON document.

list(entity_list_name=None, project_id=None)

Read all Entity metadata.

Parameters:

Name	Type	Description	Default
entity_list_name	str | None	The name of the Entity List (Dataset) being referenced.	None
project_id	int | None	The id of the project the Entity belongs to.	None

Returns:

Type	Description
list[Entity]	A list of the object representation of all Entity metadata.

merge(data, entity_list_name=None, project_id=None, match_keys=None, add_new_properties=True, update_matched=True, delete_not_matched=False, source_label_key='label', source_keys=None, create_source=None, source_size=None)

Update Entities in Central based on the provided data:

1. Create Entities from data that don't exist in Central.
2. Update Entities from data that exist in Central.
3. Optionally, delete any Entities in Central that don't exist in data.

Example input for source_data would be a list of dictionaries from a CSV file:

data = [ {"label": "Sydney", "state": "NSW", "postcode": "2000"}, {"label": "Melbourne", "state": "VIC", "postcode": "3000"}, ]

Entity creation is performed in one request using create_many. The merge operation may be slow if large quantities of updates or deletes are required, since for these operations each change is a request in a loop. If this is a concern, set the parameters update_matched and delete_not_matched to False and use the return value to perform threaded or async requests for these data.

Parameters:

Name	Type	Description	Default
data	Iterable[Mapping[str, Any]]	Data to use for updating Entities in Central.	required
entity_list_name	str | None	The name of the Entity List (Dataset) being referenced.	None
project_id	int | None	The id of the project this Entity belongs to.	None
match_keys	Iterable[str] | None	Dictionary keys common to source and target used to match rows. Defaults to ("label",). If a custom source_label_key is provided, specify that key as "label", because it is translated to "label" for matching.	None
add_new_properties	bool	If True, add any Entity List properties from data that aren't in Central.	True
update_matched	bool	If True, update any Entities in Central that match data but have different properties.	True
delete_not_matched	bool	If True, delete any Entities in Central that aren't in data.	False
source_label_key	str	The key in data to use as the label. The target label key is always "label" because this key is required by Central.	'label'
source_keys	Iterable[str] | None	If provided, process only these keys in data.	None
create_source	str | None	If Entities are created, this is used to capture the source of the change in Central, for example a file name. Defaults to the PyODK version.	None
source_size	str | None	If Entities are created, this is used to capture the size of data in Central, for example a file size. Excluded if None.	None

update(uuid, entity_list_name=None, project_id=None, label=None, data=None, force=None, base_version=None)

Update an Entity.

Parameters:

Name	Type	Description	Default
uuid	str	The unique identifier for the Entity.	required
label	str | None	Label of the Entity.	None
data	dict | None	Data to store for the Entity.	None
force	bool | None	If True, update an Entity regardless of its current state. If base_version is not specified, then force must be True.	None
base_version	int | None	The expected current version of the Entity on the server. If force is not True, then base_version must be specified.	None
entity_list_name	str | None	The name of the Entity List (Dataset) being referenced.	None
project_id	int | None	The id of the project this Entity belongs to.	None