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

# Databricks CLI — 심화

## 주요 명령어

### Workspace 관리

Workspace의 파일과 폴더를 관리합니다. 노트북, 파일, 디렉토리의 목록 조회, 내보내기, 가져오기가 가능합니다.

```bash theme={null}
# 파일/폴더 목록
databricks workspace list /Users/user@company.com

# 재귀적 목록 (하위 폴더 포함)
databricks workspace list /Users/user@company.com --recursive

# 노트북 내보내기
databricks workspace export /Users/user@company.com/notebook.py ./local/

# 폴더 전체 내보내기
databricks workspace export-dir /Users/user@company.com/project ./local/project

# 노트북 가져오기
databricks workspace import ./local/notebook.py /Users/user@company.com/notebook.py

# 폴더 전체 가져오기
databricks workspace import-dir ./local/project /Users/user@company.com/project

# 파일/폴더 삭제
databricks workspace delete /Users/user@company.com/old-notebook --recursive
```

### 클러스터 관리

클러스터의 생성, 시작, 정지, 상태 확인 등을 수행합니다.

```bash theme={null}
# 클러스터 목록
databricks clusters list

# 클러스터 상세 정보
databricks clusters get --cluster-id 0123-456789-abc

# 클러스터 시작
databricks clusters start --cluster-id 0123-456789-abc

# 클러스터 정지 (delete는 terminate을 의미)
databricks clusters delete --cluster-id 0123-456789-abc

# 클러스터 생성 (JSON 설정 파일 사용)
databricks clusters create --json '{
    "cluster_name": "my-dev-cluster",
    "spark_version": "15.4.x-scala2.12",
    "node_type_id": "m5.xlarge",
    "num_workers": 2,
    "autotermination_minutes": 30
}'

# 클러스터 이벤트 조회
databricks clusters events --cluster-id 0123-456789-abc
```

### Job 관리

Lakeflow Jobs의 생성, 실행, 모니터링을 수행합니다.

```bash theme={null}
# Job 목록
databricks jobs list

# Job 상세 정보
databricks jobs get --job-id 12345

# Job 즉시 실행
databricks jobs run-now --job-id 12345

# 파라미터와 함께 실행
databricks jobs run-now --job-id 12345 --json '{
    "notebook_params": {
        "date": "2025-03-01",
        "mode": "full_refresh"
    }
}'

# Job 실행 상태 확인
databricks runs get --run-id 67890

# 최근 실행 목록
databricks runs list --job-id 12345 --limit 10

# 실행 취소
databricks runs cancel --run-id 67890

# Job 삭제
databricks jobs delete --job-id 12345
```

### SQL 실행

SQL Warehouse를 통해 SQL 쿼리를 실행합니다.

```bash theme={null}
# SQL 쿼리 실행
databricks sql execute --warehouse-id abc123 \
    --statement "SELECT COUNT(*) FROM catalog.schema.orders"

# 결과를 JSON 형식으로 출력
databricks sql execute --warehouse-id abc123 \
    --statement "SELECT * FROM catalog.schema.orders LIMIT 5" \
    --output json

# SQL Warehouse 목록
databricks warehouses list

# SQL Warehouse 시작/정지
databricks warehouses start --id abc123
databricks warehouses stop --id abc123
```

### Volume 파일 관리

Unity Catalog Volume의 파일을 관리합니다. 로컬 파일을 업로드하거나, Volume에서 파일을 다운로드할 수 있습니다.

```bash theme={null}
# Volume 파일 목록
databricks fs ls /Volumes/catalog/schema/volume/

# 파일 업로드
databricks fs cp ./local_file.csv /Volumes/catalog/schema/volume/

# 디렉토리 전체 업로드 (재귀)
databricks fs cp ./local_dir/ /Volumes/catalog/schema/volume/data/ --recursive

# 파일 다운로드
databricks fs cp /Volumes/catalog/schema/volume/file.csv ./local/

# 디렉토리 전체 다운로드
databricks fs cp /Volumes/catalog/schema/volume/data/ ./local/data/ --recursive

# 파일 삭제
databricks fs rm /Volumes/catalog/schema/volume/old_file.csv

# 파일 내용 확인
databricks fs cat /Volumes/catalog/schema/volume/config.json
```

### Secrets 관리

비밀번호, API 키 등 민감한 정보를 안전하게 저장하고 관리합니다. Secrets는 노트북이나 Job에서 참조할 수 있지만, 평문으로 노출되지 않습니다.

```bash theme={null}
# Secret Scope 생성
databricks secrets create-scope my-secrets

# Secret 저장 (대화형 입력)
databricks secrets put-secret my-secrets db-password

# Secret 저장 (파일에서 읽기)
databricks secrets put-secret my-secrets api-key --string-value "sk-abc123..."

# Secret 목록 확인 (값은 표시되지 않음)
databricks secrets list-secrets my-secrets

# Secret Scope 목록
databricks secrets list-scopes

# Secret 삭제
databricks secrets delete-secret my-secrets old-key

# Secret Scope 삭제
databricks secrets delete-scope old-scope
```

```python theme={null}
# 노트북에서 Secret 사용
password = dbutils.secrets.get(scope="my-secrets", key="db-password")
```

### Asset Bundles

프로젝트를 코드로 정의하고, 환경별로 배포합니다. CI/CD 파이프라인의 핵심 도구입니다.

```bash theme={null}
# 프로젝트 초기화 (템플릿 선택)
databricks bundle init

# 기본 Python 템플릿으로 초기화
databricks bundle init default-python

# 설정 파일 검증
databricks bundle validate

# 로컬 변경사항 동기화 (개발 중)
databricks bundle deploy -t dev

# Job 실행
databricks bundle run my_job -t dev

# 특정 환경에 배포
databricks bundle deploy -t staging
databricks bundle deploy -t production

# 리소스 정리 (삭제)
databricks bundle destroy -t dev

# 현재 번들 상태 요약
databricks bundle summary -t dev
```

***

## 유용한 옵션

| 옵션                 | 설명                  | 사용 예시                                        |
| ------------------ | ------------------- | -------------------------------------------- |
| `--profile <name>` | 특정 인증 프로필 사용        | `databricks clusters list --profile prod`    |
| `--output json`    | 결과를 JSON 형식으로 출력    | `databricks jobs list --output json`         |
| `--output text`    | 결과를 텍스트 테이블로 출력     | `databricks clusters list --output text`     |
| `--debug`          | 디버그 로그 출력 (문제 진단 시) | `databricks clusters list --debug`           |
| `-h` / `--help`    | 도움말 표시              | `databricks jobs --help`                     |
| `--log-level`      | 로그 수준 설정            | `databricks bundle deploy --log-level debug` |

***

## 자주 사용하는 워크플로우

### 1. 개발 환경 빠른 설정

```bash theme={null}
# 새 프로젝트 시작
databricks bundle init default-python
cd my-project

# 개발 환경에 배포
databricks bundle deploy -t dev

# 코드 수정 후 재배포 + 실행
databricks bundle deploy -t dev && databricks bundle run my_job -t dev
```

### 2. 프로덕션 배포 (CI/CD)

```bash theme={null}
# CI/CD 파이프라인에서 실행
export DATABRICKS_HOST="https://dbc-prod.cloud.databricks.com"
export DATABRICKS_TOKEN="${PROD_TOKEN}"

# 검증 → 배포
databricks bundle validate -t production
databricks bundle deploy -t production
```

### 3. 대량 데이터 업로드

```bash theme={null}
# 로컬 디렉토리의 모든 파일을 Volume에 업로드
databricks fs cp ./data/ /Volumes/catalog/schema/raw_data/ --recursive --overwrite
```

### 4. 클러스터 비용 관리

```bash theme={null}
# 실행 중인 클러스터 확인
databricks clusters list --output json | python3 -c "
import json, sys
clusters = json.load(sys.stdin).get('clusters', [])
running = [c for c in clusters if c.get('state') == 'RUNNING']
for c in running:
    print(f\"{c['cluster_name']}: {c['cluster_id']} ({c.get('state')})\")
print(f'실행 중: {len(running)}개')
"
```

### 5. Job 실행 결과 모니터링

```bash theme={null}
# 최근 실패한 Job Run 확인
databricks runs list --job-id 12345 --limit 5 --output json | python3 -c "
import json, sys
runs = json.load(sys.stdin).get('runs', [])
for r in runs:
    state = r.get('state', {}).get('result_state', 'N/A')
    print(f\"Run {r['run_id']}: {state}\")
"
```

***

## 정리

| 핵심 기능             | 설명                                                               |
| ----------------- | ---------------------------------------------------------------- |
| **설치**            | Homebrew(macOS) 또는 curl(Linux/Windows)로 설치합니다. 레거시 CLI와 혼동하지 마세요 |
| **인증**            | OAuth(권장) 또는 PAT 기반으로 설정합니다. CI/CD에서는 환경 변수를 사용합니다               |
| **프로필**           | 여러 Workspace의 인증을 `~/.databrickscfg`에서 프로필로 관리합니다                |
| **Workspace**     | 노트북과 파일의 내보내기/가져오기를 수행합니다                                        |
| **Clusters**      | 클러스터의 생성, 시작, 정지, 상태 조회를 수행합니다                                   |
| **Jobs**          | Job의 생성, 실행, 모니터링, 파라미터 전달을 수행합니다                                |
| **Secrets**       | 민감한 정보를 암호화하여 안전하게 저장하고 관리합니다                                    |
| **Asset Bundles** | YAML로 프로젝트를 정의하고, 환경별로 배포합니다. CI/CD의 핵심입니다                       |

***

## 참고 링크

* [Databricks: CLI](https://docs.databricks.com/aws/en/dev-tools/cli/)
* [Databricks: CLI commands](https://docs.databricks.com/aws/en/dev-tools/cli/commands.html)
* [Databricks: CLI authentication](https://docs.databricks.com/aws/en/dev-tools/cli/authentication.html)
* [Databricks: Asset Bundles](https://docs.databricks.com/aws/en/dev-tools/bundles/)
* [Databricks: Secrets CLI](https://docs.databricks.com/aws/en/dev-tools/cli/secrets-cli.html)