insert_database_entry#

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

Insert new database entries into an AMS database form.

Processes a pandas.DataFrame containing database entry data, validates it, and inserts new entries into the specified AMS database form via the API. Supports table fields and customizable options for caching and interactive feedback. See Database Operations for database workflows.

Parameters:

  • df (pandas.DataFrame) – DataFrame with database entry data. Columns represent form fields (e.g., ‘Allergy’), and rows contain values. 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 (InsertDatabaseOption, optional) – Configuration options, including table_fields for table field names, interactive_mode for status messages (e.g., “Inserted 3 entries”), and cache to reuse a client. Defaults to None (uses default InsertDatabaseOption).

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

Returns:

The function does not return a value but inserts entries into the AMS database

and prints status messages if interactive_mode is enabled.

Return type:

None

Raises:

  • AMSError – If form is empty, not a database form, authentication fails, df is invalid (e.g., empty), or the API request fails.

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

Examples

>>> import pandas as pd
>>> from teamworksams import insert_database_entry, InsertDatabaseOption
>>> df = pd.DataFrame({
...     "Allergy": ["Dairy", "Eggs", "Peanuts"]
... })
>>> insert_database_entry(
...     df = df,
...     form = "Allergies",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass"
... )
ℹ Inserting 3 database entries for form 'Allergies'
✔ Processed 3 database entries for form 'Allergies'
ℹ Form: Allergies
ℹ Result: Success
ℹ Records inserted: 3
ℹ Records attempted: 3

Additional Notes#

  • The df must contain columns matching the AMS form’s fields (e.g., ‘Allergy’); missing or invalid data raises AMSError.

  • Use option.table_fields to specify table fields, ensuring column names match exactly to avoid errors.

  • Enable option.interactive_mode=True for status messages like “Inserted 3 entries,” ideal for interactive scripts.

See Also#