API Reference

The SnowEx Python API provides two access paths to the database:

• Direct database access (snowexsql.api) — for users with database credentials. Queries run locally against the PostgreSQL/PostGIS database using SQLAlchemy.

• Lambda client (snowexsql.lambda_client) — for users without credentials. Queries are sent to a public AWS Lambda Function URL that proxies the request to the database server-side. No AWS account or database credentials are required.

Both paths expose the same high-level interface: from_filter(), from_area(), from_unique_entries(), and all_* properties.

Note

By default, queries are capped at 1000 records. If your query would return more, a LargeQueryCheckException is raised unless you explicitly pass limit=<n> with a value larger than 1000.

Direct Database API

BaseDataset

class snowexsql.api.BaseDataset

Bases: object

Base class for all SnowEx measurement dataset accessors.

Provides filtering, querying, and property-based access to measurements stored in the SnowEx database. Subclasses must set MODEL to the appropriate SQLAlchemy table class.

ALLOWED_QRY_KWARGS = ['campaign', 'date', 'instrument', 'type', 'utm_zone', 'date_greater_equal', 'date_less_equal', 'value_greater_equal', 'value_less_equal', 'doi', 'observer']

MAX_RECORD_COUNT = 1000

MODEL = None

SPECIAL_KWARGS = ['limit']

property all_campaigns

Return all campaign names

property all_dates

Return all distinct dates in the data

property all_dois

Return all distinct DOIs in the data

property all_instruments

Return all distinct instruments in the data

property all_observers

Return all distinct observers in the data

property all_types

Return all types of the data

property all_units

Return all distinct units in the data

classmethod extend_qry(qry, check_size=True, **kwargs)

classmethod from_area(verbose=False, shp=None, pt=None, buffer=None, crs=26912, **kwargs)

Get data for the class within a specific shapefile or within a point and a known buffer. Uses PostGIS functions via ORM for spatial operations, eliminating dependency on geoalchemy2/shapely.

Args:

verbose: If True, return denormalized data with related table columns shp: shapely geometry in which to filter, or WKT string pt: shapely point that will have a buffer applied, or WKT string buffer: buffer distance in same units as point (meters if using geography) crs: integer SRID/EPSG code (default 26912 = UTM Zone 12N) kwargs: for more filtering or limiting (cls.ALLOWED_QRY_KWARGS)

Returns:

pandas DataFrame with results (includes geom column with WKT)

classmethod from_filter(verbose=False, **kwargs)

Get data for the class by filtering by allowed arguments. The allowed filters are cls.ALLOWED_QRY_KWARGS.

Args:

verbose: If True, return denormalized data with related table columns kwargs: Filter arguments from ALLOWED_QRY_KWARGS

classmethod from_unique_entries(columns_to_search, **kwargs)

Returns unique values from a column to help with filtering

static retrieve_single_value_result(result)

When we only request a single thing we still get a list of lists this function filters it out. This usually looks like a list of tuples.

PointMeasurements

class snowexsql.api.PointMeasurements

Bases: BaseDataset

API class for access to PointData

MODEL

alias of PointData

property all_instruments

Return all distinct instruments in the data

property all_types

Return all measurement types that have data in the points table

LayerMeasurements

class snowexsql.api.LayerMeasurements

Bases: BaseDataset

API class for access to LayerData

ALLOWED_QRY_KWARGS = ['campaign', 'site', 'date', 'instrument', 'observer', 'type', 'utm_zone', 'date_greater_equal', 'date_less_equal', 'doi', 'value_greater_equal', 'value_less_equal']

MODEL

alias of LayerData

property all_dates

Return all distinct dates in the data

property all_sites

Return all specific site names

property all_types

Return all measurement types that have data in the layers table

property all_units

Return all distinct units in the data

classmethod get_sites(site_names=None, **kwargs)

Get site information including geometries.

Args:

site_names: List of site names or single site name kwargs: Additional filters (campaign, date, etc.)

Returns:

GeoDataFrame with site information

Exceptions

exception snowexsql.api.LargeQueryCheckException

Lambda Client

SnowExLambdaClient

class snowexsql.lambda_client.SnowExLambdaClient(function_url: str | None = None)

Bases: object

Client for accessing SnowEx data via AWS Lambda Function URL

This client provides serverless access to the SnowEx database through a public Lambda Function URL, eliminating the need for AWS credentials, database connections, or heavy geospatial dependencies.

The Lambda function handles all database credentials securely via AWS Secrets Manager.

The client mirrors the api.py class structure, providing access to: - PointMeasurements: Point data measurements - LayerMeasurements: Layer/profile data measurements - RasterMeasurements: Raster/image data - System functions: DOI queries, connection testing

Example:

>>> client = SnowExLambdaClient()
>>> client.test_connection()
{'connected': True, 'version': 'PostgreSQL 17.6...'}

>>> # Use class-based approach (mirrors api.py)
>>> data = client.layer_measurements.from_filter(
...     instrument='reflectance', limit=10
... )
>>> instruments = client.point_measurements.all_instruments

DEFAULT_FUNCTION_URL = 'https://izwsawyfkxss5vawq5v64mruqy0ahxek.lambda-url.us-west-2.on.aws'

REQUEST_TIMEOUT_SECONDS = 30

get_measurement_classes()

Get all measurement client objects as a dictionary for easy unpacking.

This method dynamically discovers all available measurement classes and returns them with their original CamelCase names, making it easy to use as drop-in replacements for direct API imports.

Returns:

Dict mapping class names (str) to client objects

Example:

>>> from snowexsql.lambda_client import SnowExLambdaClient
>>> client = SnowExLambdaClient()
>>> 
>>> # Get all measurement classes
>>> classes = client.get_measurement_classes()
>>> PointMeasurements = classes['PointMeasurements']
>>> LayerMeasurements = classes['LayerMeasurements']
>>> 
>>> # Use exactly like the direct API
>>> df = PointMeasurements.from_filter(type='depth', limit=10)
>>> df.plot(column='value', cmap='jet')

query(sql_query: str) → DataFrame

Execute a raw SQL query against the database via Lambda.

Args:

sql_query: Raw SQL query string to execute

Returns:

pd.DataFrame: Query results as a DataFrame

test_connection() → Dict[str, Any]

Test database connection through Lambda

Returns:

Dict with connection status and database version info

create_client

snowexsql.lambda_client.create_client(function_url: str | None = None) → SnowExLambdaClient

Create a SnowExLambdaClient instance

Args:

function_url: Lambda Function URL (optional)

Returns:

SnowExLambdaClient instance