CRUD Monday
connectx.crud.monday
GraphQL
Represents a GraphQL field or object structure for querying the Monday.com API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name of the field or object. |
required |
fields
|
list
|
Optional list of nested fields for this object. |
None
|
attributes
|
dict
|
Optional dictionary of attributes for this field/object. |
None
|
Monday
Bases: Rest
Interface for interacting with Monday.com API using REST/GraphQL requests.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
access_token
|
str
|
Monday.com API access token. |
required |
mapping
|
str | list[str]
|
Optional CSV file(s) or list of CSV filenames for board/column mappings. |
None
|
n_rows_read
|
int
|
Number of rows to read per request. |
500
|
n_rows_write
|
int
|
Number of rows to write per batch request. |
100
|
die_on_error
|
bool
|
Raise exceptions on errors if True. |
True
|
timeout
|
Request timeout in seconds. |
120
|
|
verify
|
SSL certificate verification. |
None
|
|
cert
|
Client certificate. |
None
|
create
Create a new item on a Monday.com board.
Converts human-readable data into Monday.com IDs and sends a GraphQL mutation request to create the item.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
module
|
str | int
|
Board ID or board name where the item will be created. |
required |
data
|
dict
|
Dictionary of item data (column values, name, etc.). |
required |
Returns:
| Type | Description |
|---|---|
int | None
|
ID of the created item or None if creation failed. |
delete
Delete an item from a Monday.com board.
Sends a GraphQL mutation request to remove the specified item.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
module
|
str | int
|
Board ID or board name. |
required |
id
|
str | int
|
ID of the item to delete. |
required |
Returns:
| Type | Description |
|---|---|
bool | None
|
ID of the deleted item, or None if deletion failed. |
get_board_columns
Retrieve the columns of a given board.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
board_id
|
int
|
ID of the board. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary of columns keyed by column ID. |
get_board_id
Retrieve the board ID and its string representation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
module
|
int | str
|
Board ID as int or board name/ID string. |
required |
Returns:
| Type | Description |
|---|---|
tuple[str, int]
|
Tuple containing (board name or ID as string, board ID as int). |
get_id
Get the ID corresponding to a given name in a specified section.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
section
|
Section name to search in. |
required | |
name
|
Name of the item to find. |
required | |
workspace
|
Optional workspace filter. |
None
|
Returns:
| Type | Description |
|---|---|
|
The ID of the item. |
get_name
Get the name corresponding to a given ID in a specified section.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
section
|
Section name to search in. |
required | |
id
|
ID of the item to find. |
required | |
workspace
|
Optional workspace filter. |
None
|
Returns:
| Type | Description |
|---|---|
|
The name of the item. |
headers
Returns the default headers for Monday.com API requests, including authorization and content type.
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary of HTTP headers. |
human_to_monday
Convert human-readable names/values into Monday.com IDs for a given module.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
module
|
str | int
|
Module or board name/ID. |
required |
data
|
str | list | dict | DataFrame
|
Data to convert; can be a string, list, dict, or DataFrame. |
required |
Returns:
| Type | Description |
|---|---|
|
Data with human-readable names replaced by corresponding Monday.com IDs. |
integrate
Create or update an item on a Monday.com board based on a synchronization key.
Checks if an item with the given sync_key exists: - If it exists, updates the item. - Otherwise, creates a new item.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
module
|
str | int
|
Board ID or board name. |
required |
data
|
dict
|
Dictionary of item data. |
required |
sync_key
|
str
|
Column used to determine if an item exists. |
required |
Returns:
| Type | Description |
|---|---|
int | None
|
ID of the created or updated item. |
load
Bulk load items into a Monday.com board.
Supports create, update, and integrate actions for multiple rows of data. Data can be transformed before sending, and a callback can be provided for progress updates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
module
|
str | int
|
Board ID or board name. |
required |
data
|
DataFrame
|
Polars DataFrame containing rows to load. |
required |
action
|
int
|
Action type (CREATE, UPDATE, INTEGRATE). |
required |
sync_key
|
str
|
Column used for integration actions. |
None
|
transform
|
Optional function to transform each row before sending. |
None
|
|
picklist
|
dict
|
Optional dictionary for picklist values used in transformation. |
None
|
n_rows_write
|
int
|
Number of rows to write per batch. |
None
|
die_on_error
|
bool
|
If True, raises an exception if any row fails. |
False
|
callback
|
callable
|
Optional function called during processing to report progress. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
Polars DataFrame containing original data with additional columns "success" and "message". |
monday_to_human
Convert Monday.com IDs into human-readable names/values for a given module.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
module
|
str | int
|
Module or board name/ID. |
required |
data
|
Data to convert; can be a string, list, dict, or DataFrame. |
required |
Returns:
| Type | Description |
|---|---|
|
Data with Monday.com IDs replaced by corresponding human-readable names. |
move_to_group
Move an item to a different group within a Monday.com board.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
module
|
str | int
|
Board ID or board name. |
required |
id
|
str | int
|
ID of the item to move. |
required |
group
|
str
|
Group ID or name where the item should be moved. |
required |
Returns:
| Type | Description |
|---|---|
bool | None
|
Result of the mutation request. |
mutation
Executes a GraphQL mutation on a Monday.com object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name of the mutation or object to modify. |
required |
fields
|
list
|
Optional list of fields to retrieve in response. |
None
|
attributes
|
dict
|
Optional dictionary of attributes for the mutation. |
None
|
Returns:
| Type | Description |
|---|---|
|
API response as a dictionary. |
normalize_data
Convert a dictionary of board data into the format required by the Monday.com API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
board_id
|
int
|
ID of the board. |
required |
data
|
dict
|
Dictionary of data to normalize. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary with normalized column values suitable for API submission. |
normalize_filter
Convert a dictionary of filter criteria into the format required by the Monday.com API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
board_id
|
int
|
ID of the board. |
required |
data
|
dict
|
Dictionary of filter criteria to normalize. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary with normalized column values suitable for API filtering. |
ping
Check connectivity with Monday.com API.
Returns:
| Type | Description |
|---|---|
bool
|
True if API is reachable, False otherwise. |
query
Executes a GraphQL query and returns the results as a Polars DataFrame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name of the object or field to query. |
required |
fields
|
list
|
Optional list of fields to retrieve. |
None
|
attributes
|
dict
|
Optional dictionary of attributes for the query. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
Polars DataFrame with query results. |
read
Read items from a Monday.com board with optional filtering, field selection, and pagination.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
module
|
str | int
|
Board ID or board name to read from. |
required |
filter
|
dict
|
Dictionary of filter criteria to apply. |
None
|
fields
|
list
|
List of fields/columns to include in the output. |
None
|
order_by
|
str
|
Field name to order the results by. Default is "id". |
'id'
|
limit
|
int
|
Maximum number of rows to retrieve. |
None
|
callback
|
callable
|
Optional callable to track progress. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
Polars DataFrame containing the normalized and human-readable data from the board. |
request
Sends a request to the Monday.com API using GraphQL or REST.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
str
|
HTTP method ("GET" or "POST"). |
required |
query
|
str | GraphQL | list[str | GraphQL]
|
Single query string, GraphQL object, or list of queries. |
required |
path
|
str
|
API endpoint path. Default is "v2". |
'v2'
|
headers
|
dict
|
Optional custom headers. |
None
|
raise_on_error
|
bool
|
Raise an exception if an error occurs. Default True. |
True
|
kwargs
|
Additional request parameters. |
{}
|
Returns:
| Type | Description |
|---|---|
dict | None
|
API response as a dictionary or None. |
retrieve
Retrieve a single item from a Monday.com board by ID.
Explodes column_values into individual columns and converts Monday.com IDs to human-readable names.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
module
|
str | int
|
Board ID or board name. |
required |
id
|
int
|
Item ID to retrieve. |
required |
Returns:
| Type | Description |
|---|---|
dict | None
|
Dictionary with item data, including column values as human-readable fields. |
set_default_workspace
Sets the default workspace for subsequent operations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workspace
|
int | str
|
Workspace ID or name to set as default. |
None
|
board_id
|
str | int
|
Board ID to infer the workspace from. |
None
|
item_id
|
int
|
Item ID to infer the workspace from. |
None
|
Returns:
| Type | Description |
|---|---|
int
|
The ID of the workspace set as default. |
unnest
Recursively flattens nested structures and special column types in a Polars DataFrame.
Handles Struct columns, column_values (including people, board_relation, dependency, checkbox, time_tracking, mirror, formula, date, text), and List columns. Repeats the process up to the specified depth.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
df
|
DataFrame
|
Polars DataFrame to unnest. |
required |
depth
|
int
|
Maximum number of recursive unnesting iterations. Default is 2. |
2
|
Returns:
| Type | Description |
|---|---|
|
Flattened Polars DataFrame with nested fields expanded. |
update
Update an existing item on a Monday.com board.
Converts human-readable data into Monday.com IDs and sends a GraphQL mutation request to update the item.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
module
|
str | int
|
Board ID or board name. |
required |
data
|
dict
|
Dictionary of updated item data. |
required |
id
|
ID of the item to update. If not provided, it must be included in |
None
|
Returns:
| Type | Description |
|---|---|
int | None
|
ID of the updated item, or None if update failed. |