> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pysquirrels.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DateRangeDataSource

> Lookup table for date range parameter options

Data source class for populating date range parameter options from a database table or query.

This class can be imported from the `squirrels.data_sources` or the `squirrels` module.

## Constructor

Creates a `DateRangeDataSource` object.

```python theme={null}
def __init__(
    self, table_or_query: str, default_start_date_col: str, 
    default_end_date_col: str, 
    *, date_format: str = '%Y-%m-%d', min_date_col: str | None = None, 
    max_date_col: str | None = None, id_col: str | None = None, 
    source: SourceEnum = SourceEnum.CONNECTION, user_group_col: str | None = None, 
    parent_id_col: str | None = None, connection: str | None = None
) -> None:
```

<Expandable title="arguments" defaultOpen>
  <ResponseField name="table_or_query" type="str" required>
    Either the name of the table to use, or a SQL query to run. If using a SQL query, it must start with "SELECT" (ignoring case and leading whitespaces) followed by a whitespace.

    The available tables are based on the `source` argument. If the source is `SourceEnum.CONNECTION`, then the SQL syntax is based on the underlying database from the `connection` argument. Otherwise, the SQL syntax is DuckDB SQL.
  </ResponseField>

  <ResponseField name="default_start_date_col" type="str" required>
    The column name for the default start date.
  </ResponseField>

  <ResponseField name="default_end_date_col" type="str" required>
    The column name for the default end date.
  </ResponseField>

  <ResponseField name="min_date_col" type="str | None" default="None">
    The column name for the minimum date. If None, then there is no minimum date constraint.
  </ResponseField>

  <ResponseField name="max_date_col" type="str | None" default="None">
    The column name for the maximum date. If None, then there is no maximum date constraint.
  </ResponseField>

  <ResponseField name="date_format" type="str" default="'%Y-%m-%d'">
    Format of the dates in the columns. Uses Python's `strftime` format codes (e.g., `%Y-%m-%d` for ISO format, `%m/%d/%Y` for US format).
  </ResponseField>

  <ResponseField name="source" type="SourceEnum" default="SourceEnum.CONNECTION">
    The source to fetch data from as a [SourceEnum](/references/python/data_sources/sourceenum) value.
  </ResponseField>

  <ResponseField name="user_group_col" type="str | None" default="None">
    The column name of the user group for option visibility. If None, all users will see all options.
  </ResponseField>

  <ResponseField name="parent_id_col" type="str | None" default="None">
    The column name of the parent option id for cascading.

    If None, then this parameter has no parent and its options will not be cascaded.
  </ResponseField>

  <ResponseField name="connection" type="str | None" default="None">
    Name of the connection to use. Only used if the source is `SourceEnum.CONNECTION`. Connection must be defined in `squirrels.yml` or the `connections.py` file.

    If None, uses the default connection (specified by `SQRL_CONNECTIONS__DEFAULT_NAME_USED` environment variable or 'default').
  </ResponseField>
</Expandable>

## Examples

A `DateRangeDataSource` object is created in the `pyconfigs/parameters.py` file. It must be created in a function decorated with the `create_from_source` factory method from [DateRangeParameter](/references/python/parameters/daterangeparameter).

### Usage example in parameters.py

```python highlight="9-21" theme={null}
from squirrels import parameters as p, data_sources as ds

@p.DateRangeParameter.create_from_source(
    name="reporting_period", 
    label="Reporting Period",
    description="Date range for the report"
)
def reporting_period_source():
    return ds.DateRangeDataSource(
        table_or_query="""
            SELECT 
                CURRENT_DATE - INTERVAL '30 days' AS default_start,
                CURRENT_DATE AS default_end,
                CURRENT_DATE - INTERVAL '1 year' AS min_date,
                CURRENT_DATE AS max_date
        """,
        default_start_date_col="default_start",
        default_end_date_col="default_end",
        min_date_col="min_date",
        max_date_col="max_date"
    )
```

In addition, the following are some additional examples for creating a `DateRangeDataSource` object.

### Using a table from a specific connection

This example uses a table called "fiscal\_periods" from the "analytics\_db" connection.

```python highlight="2,7" theme={null}
ds.DateRangeDataSource(
    table_or_query="fiscal_periods",
    default_start_date_col="period_start",
    default_end_date_col="period_end",
    min_date_col="fiscal_year_start",
    max_date_col="fiscal_year_end",
    connection="analytics_db"
)
```

The connection must either be defined in `squirrels.yml` or the `connections.py` file.

### Using seeds as the data source

This example uses a seed file called "date\_range\_config".

```python highlight="2,5" theme={null}
ds.DateRangeDataSource(
    table_or_query="date_range_config",
    default_start_date_col="start_date",
    default_end_date_col="end_date",
    source=ds.SourceEnum.SEEDS
)
```

### Using a custom date format

This example demonstrates using a different date format for the dates stored in the database.

```python highlight="9" theme={null}
ds.DateRangeDataSource(
    table_or_query="""
        SELECT 
            '01/01/2025' AS start_date,
            '12/31/2025' AS end_date
    """,
    default_start_date_col="start_date",
    default_end_date_col="end_date",
    date_format="%m/%d/%Y"
)
```

### Enabling cascading effects with a parent parameter

In this example, the date range is determined by the selected value of another parameter called "quarter".

```python highlight="5,14" theme={null}
@p.DateRangeParameter.create_from_source(
    name="analysis_period", 
    label="Analysis Period",
    description="The date range for the selected quarter",
    parent_name="quarter"
)
def analysis_period_source():
    return ds.DateRangeDataSource(
        table_or_query="quarterly_periods",
        default_start_date_col="quarter_start_date",
        default_end_date_col="quarter_end_date",
        min_date_col="year_start_date",
        max_date_col="year_end_date",
        parent_id_col="quarter_id"  # Cascades based on quarter selection
    )
```