update_database_entry#

teamworksams.database_main.update_database_entry(df: pandas.DataFrame, form: str, url: str, username: str | None = None, password: str | None = None, option: UpdateDatabaseOption | None = None, client: AMSClient | None = None) → None[source]#

Update existing database entries in an AMS database form.

Processes a pandas.DataFrame with an ‘entry_id’ column to update existing entries in the specified AMS database form via the API. Validates data, supports table fields, and offers interactive confirmation prompts. See Database Operations for database workflows.

Parameters:

  • df (pandas.DataFrame) – DataFrame with database entry data. Must include ‘entry_id’ (valid integer IDs) and columns for fields to update (e.g., ‘Allergy’). Must not be empty.

  • form (str) – Name of the AMS database form (e.g., ‘Allergies’). Must be a non-empty string and correspond to a valid database form.

  • url (str) – AMS instance URL (e.g., ‘https://example.smartabase.com/site’). Must include a valid site name.

  • username (Optional[str]) – Username for authentication. If None, uses AMS_USERNAME or keyring credentials. Defaults to None.

  • password (Optional[str]) – Password for authentication. If None, uses AMS_PASSWORD or keyring credentials. Defaults to None.

  • option (UpdateDatabaseOption, optional) – Configuration options, including table_fields for table field names, interactive_mode for status messages and confirmation prompts, and cache to reuse a client. Defaults to None (uses default UpdateDatabaseOption).

  • client (AMSClient, optional) – Pre-authenticated client from get_client(). If None, a new client is created. Defaults to None.

Returns:

Updates entries in the AMS database and prints status messages if

option.interactive_mode=True.

Return type:

None

Raises:

  • AMSError – If form is empty, not a database form, authentication fails, df is invalid (e.g., empty, missing ‘entry_id’), user cancels in interactive mode, or the API request fails.

  • ValueError – If table_fields contains invalid field names not in df.

Examples

>>> import pandas as pd
>>> from teamworksams import update_database_entry, UpdateDatabaseOption
>>> df = pd.DataFrame({
...     "entry_id": [386197, 386198, 386199],
...     "Allergy": ["Dairy Updated", "Eggs Updated", "Peanuts Updated"]
... })
>>> update_database_entry(
...     df = df,
...     form = "Allergies",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     option = UpdateDatabaseOption(interactive_mode = True)
... )
ℹ Updating 3 database entries for form 'Allergies'
Are you sure you want to update 3 existing database entries in 'Allergies'? (y/n): y
✔ Processed 3 database entries for form 'Allergies'
ℹ Form: Allergies
ℹ Result: Success
ℹ Records updated: 3
ℹ Records attempted: 3

Additional Notes#

  • The df must include ‘entry_id’ with valid integer IDs; invalid IDs raise AMSError. Use get_database() to retrieve IDs.

  • Set option.interactive_mode=True to prompt for confirmation before updating, preventing accidental changes.

  • Use option.table_fields to update table fields, ensuring column names match the AMS form.

See Also#