get_database#

teamworksams.database_main.get_database(form_name: str, url: str, username: str | None = None, password: str | None = None, limit: int = 10000, offset: int = 0, option: GetDatabaseOption | None = None, client: AMSClient | None = None) → pandas.DataFrame[source]#

Retrieve database entries from an AMS database form.

Fetches entries from a specified AMS database form, returning a pandas.DataFrame with columns for entry IDs and field values. Supports pagination via limit and offset, and customization through GetDatabaseOption for caching, interactive feedback, or raw output. Ideal for retrieving structured data like allergies or equipment lists. See Database Operations for database workflows.

Parameters:

  • form_name (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. Defaults to None.

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

  • limit (int) – Maximum number of entries to return per request. Must be positive (e.g., 10000). Use smaller values for large datasets to manage memory. Defaults to 10000.

  • offset (int) – Starting index for pagination. Must be non-negative. Use to skip entries in large datasets (e.g., 10000 for the next batch). Defaults to 0.

  • option (GetDatabaseOption, optional) – Configuration options, including interactive_mode for status messages (e.g., “Retrieved 100 entries”), cache to reuse a client, and raw_output for unprocessed API responses. Defaults to None (uses default GetDatabaseOption).

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

Returns:

Database entries with columns like ‘id’ and

form-specific fields (e.g., ‘Allergy’). Returns an empty DataFrame if no entries are found

Return type:

pandas.DataFrame

Raises:

  • AMSError – If form_name is empty, not a database form, authentication fails, or the API request fails.

  • ValueError – If limit is not positive or offset is negative.

Examples

>>> from teamworksams import get_database
>>> df = get_database(
...     form_name = "Allergies",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     limit = 100,
...     offset = 0
... )
>>> print(df)
   id  Allergy
0  386197   Dairy
1  386198    Eggs
2  386199  Peanuts

Additional Notes#

  • The form_name must match an existing AMS database form exactly (case-sensitive); invalid forms raise AMSError.

  • Use limit and offset for pagination, e.g., set limit=1000 and increment offset by 1000 to fetch large datasets in batches.

  • Enable option.interactive_mode=True for feedback like “Retrieved 100 entries,” useful in interactive environments.

See Also#