# Utilities

```{eval-rst}
.. verified:: 2025-01-21
   :reviewer: Christof Buchbender
```

This page documents utilities for database initialization and data loading. These are
used for setting up a fresh database instance.

## Database Initialization

The `opsdb_init` command-line tool initializes a fresh ops-db instance with
observatory infrastructure, instruments, and observation units.

```{eval-rst}
.. autofunction:: ccat_ops_db.opsdb_init.opsdb_initialization
```

Command-Line Usage:

```
# Initialize with default settings
opsdb_init

# Initialize and drop existing tables
opsdb_init --drop

# Initialize with local data-center repository
opsdb_init --local_url /path/to/data-center

# Initialize for production mode
opsdb_init --data_archive_mode production

# Verbose output
opsdb_init -v --drop
```

## Observation Unit Initialization

```{eval-rst}
.. autofunction:: ccat_ops_db.init_obs_units.init_obs_units
```

```{eval-rst}
.. autofunction:: ccat_ops_db.init_obs_units.read_obs_units
```

```{eval-rst}
.. autofunction:: ccat_ops_db.init_obs_units.read_sources
```

```{eval-rst}
.. autofunction:: ccat_ops_db.init_obs_units.read_pre_scheduled_slots
```

These functions parse YAML/CSV files from the data-center repository and populate the
database with sources, observation units, and scheduling information.

## Utility Functions

These functions provide helpers for adding or updating database entities.

### Sources

```{eval-rst}
.. autofunction:: ccat_ops_db.utils.add_or_update_source
```

Example:

```
from ccat_ops_db.utils import add_or_update_source

values = {
    "name": "Orion-KL",
    "slam": "05:35:14.5",
    "sbet": "-05:22:30.0",
    "frame": "icrs",
    "vlsr": 9.0
}
add_or_update_source(session, values, source_type="fixed_source")
```

### Observation Units

```{eval-rst}
.. autofunction:: ccat_ops_db.utils.add_or_update_obs_unit
```

```{eval-rst}
.. autofunction:: ccat_ops_db.utils.add_inpar_and_tiling
```

### Pre-Scheduled Slots

```{eval-rst}
.. autofunction:: ccat_ops_db.utils.add_pre_scheduled_slot
```

## Data Center Repository Structure

The initialization process expects data files in the [data-center](https://github.com/ccatobs/data-center)
repository with the following structure:

```
data-center/
├── observatory/
│   └── *.toml (observatory definitions)
├── telescope/
│   └── *.toml (telescope definitions)
├── instruments/
│   └── *.toml (instrument and module definitions)
├── roles/
│   └── *.toml (user role definitions)
├── users/
│   └── *.toml (user definitions)
├── observing_programs/
│   └── *.toml (observing program definitions)
├── lines/
│   └── *.toml (spectral line definitions)
├── obs_modes/
│   └── *.toml (observation mode definitions)
├── sites/
│   ├── sites.development.toml
│   ├── sites.staging.toml
│   └── sites.production.toml (site and location definitions)
└── obs_units/
    ├── input_file_obs_units_to_db.yaml (master input file)
    ├── sources/
    ├── obsunits/
    ├── inpar_parameters/
    └── tiling_parameters/
```

The `--data_archive_mode` flag selects which sites configuration to load
(development, staging, or production).

## Related Documentation

- Core functions: {doc}`core`
- Models API: {doc}`models`
- Database concepts: {doc}`../concepts/overview`