# 機能設計書 444-Get-DbaReplArticleColumn

## 概要

本ドキュメントは、SQL Serverパブリケーションアーティクルの列レベルのレプリケーション構成詳細を取得するdbatools PowerShellコマンドレット `Get-DbaReplArticleColumn` の機能設計を記述する。

### 本機能の処理概要

Get-DbaReplArticleColumnは、レプリケーションアーティクルに含まれる列の詳細情報を取得するコマンドレットである。垂直パーティショニング（列フィルタリング）シナリオで特に有用。

**業務上の目的・背景**：レプリケーション構成において、どの列がサブスクライバーにレプリケートされているかを把握することは、データ同期の監査やトラブルシューティングに不可欠である。特に垂直パーティショニングを使用している場合、ソーステーブルの一部の列のみがレプリケートされるため、この情報の確認が重要となる。

**機能の利用シーン**：
- 垂直パーティショニング構成の監査時に、どの列がレプリケートされているかを確認する場面
- サブスクライバーで特定の列が表示されない問題のトラブルシューティング
- レプリケーション構成のドキュメント化
- 列レベルでのレプリケーション設定の比較

**主要な処理内容**：
1. Get-DbaReplArticleを呼び出してアーティクル情報を取得
2. 各アーティクルに対してLoadProperties()を呼び出し
3. ソーステーブルのSMOオブジェクトを取得
4. 垂直パーティショニングの有無を確認
5. パーティショニング無効時: テーブルの全列を取得
6. パーティショニング有効時: sysarticlecolumnsテーブルからレプリケート対象列を取得
7. Columnパラメータでフィルタリング
8. 各列情報にメタデータを追加して出力

**関連システム・外部連携**：
- Get-DbaReplArticleに依存
- SMO (Server Management Objects) を使用してテーブル情報を取得
- Invoke-DbaQueryでsysarticlecolumnsシステムテーブルをクエリ

**権限による制御**：
- SQL Serverインスタンスへのアクセス権限が必要
- レプリケーションメタデータの読み取り権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主画面 | PowerShellコマンドラインから直接実行 |

## 機能種別

データ取得 / 情報参照

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス | 有効なSQL Serverインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | Get-Credentialで取得した有効な認証情報 |
| Database | object[] | No | フィルタリング対象のデータベース名 | ワイルドカード対応 |
| Publication | object[] | No | フィルタリング対象のパブリケーション名 | ワイルドカード対応 |
| Article | string[] | No | フィルタリング対象のアーティクル名 | ワイルドカード対応 |
| Column | string[] | No | フィルタリング対象の列名 | 完全一致 |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

PowerShellコマンドライン引数、パイプライン入力（SqlInstance, Publicationパラメータ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| DatabaseName | string | パブリケーションを含むデータベース名 |
| PublicationName | string | パブリケーション名 |
| ArticleName | string | アーティクル名 |
| ArticleId | int | アーティクルの一意識別子 |
| ColumnName | string | 列名 |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. processブロック
   └─ Test-FunctionInterruptで中断チェック
   └─ Get-DbaReplArticleを呼び出してアーティクル取得
2. 各アーティクルに対してループ
   └─ LoadProperties()を実行
   └─ SMOでソーステーブルを取得
   └─ テーブルが見つからない場合は警告を出力してスキップ
   └─ VerticalPartitionを確認
       └─ False: テーブルの全列を取得
       └─ True: sysarticlecolumnsをクエリして列を取得
   └─ Columnパラメータでフィルタリング
   └─ 各列にメタデータを追加して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Test-FunctionInterrupt?}
    B -->|Yes| C[終了]
    B -->|No| D[Get-DbaReplArticle]
    D --> E[アーティクルループ]
    E --> F[LoadProperties]
    F --> G[SMOでテーブル取得]
    G --> H{テーブル存在?}
    H -->|No| I[Warning出力]
    I --> J{次のアーティクル?}
    H -->|Yes| K{VerticalPartition?}
    K -->|No| L[全列取得]
    K -->|Yes| M[sysarticlecolumnsクエリ]
    L --> N{Columnフィルタ?}
    M --> N
    N -->|Yes| O[列フィルタリング]
    N -->|No| P[メタデータ追加]
    O --> P
    P --> Q[Select-DefaultView]
    Q --> J
    J -->|Yes| E
    J -->|No| C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 全列レプリケーション | VerticalPartition=falseの場合、テーブルの全列がレプリケート対象 | VerticalPartition=false |
| BR-002 | 部分列レプリケーション | VerticalPartition=trueの場合、sysarticlecolumnsから列を取得 | VerticalPartition=true |
| BR-003 | 完全一致フィルタ | Columnパラメータは完全一致でフィルタリング | Columnパラメータ指定時 |

### 計算ロジック

垂直パーティショニング時の列取得クエリ:
```sql
SELECT c.name as ColumnName
FROM sysarticlecolumns ac
INNER JOIN sys.columns c ON ac.colid = c.column_id
INNER JOIN sys.tables t ON c.object_id = t.object_id AND ac.artid = (
    SELECT artid FROM sysarticles WHERE name = @articleName
)
WHERE t.name = @tableName
    AND SCHEMA_NAME(t.schema_id) = @schemaName
ORDER BY c.column_id
```

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| アーティクル列取得 | sysarticlecolumns, sysarticles, sys.columns, sys.tables | SELECT | 垂直パーティショニング時に列情報を取得 |

### テーブル別操作詳細

#### sysarticlecolumns（VerticalPartition=true時のみ）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | artid, colid | アーティクルID、列IDの取得 | sysarticlesとJOIN |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Warning | ソーステーブルが見つからない | アーティクルの構成を確認 |
| - | ProcessError | アーティクル列取得失敗 | レプリケーション構成を確認 |

### リトライ仕様

自動リトライは行わない。Stop-Functionで処理を停止し、-Continueで次のアーティクルの処理を継続する。

## トランザクション仕様

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

アーティクル数と列数に依存するが、通常は数秒以内に完了する。

## セキュリティ考慮事項

- 認証情報はPSCredentialとして安全に処理される
- レプリケーションメタデータの読み取りには適切な権限が必要

## 備考

- Description, Type, VerticalPartition, SourceObjectOwner, SourceObjectNameなどの追加プロパティも取得可能
- ストアドプロシージャやビューのアーティクルには列情報がない場合がある

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaReplArticle.ps1 | `public/Get-DbaReplArticle.ps1` | アーティクルオブジェクトの構造 |

**読解のコツ**: VerticalPartitionプロパティが列取得ロジックの分岐点となる。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaReplArticleColumn.ps1 | `public/Get-DbaReplArticleColumn.ps1` | メインのコマンドレット実装 |

**主要処理フロー**:
1. **114行目**: Get-DbaReplArticleを呼び出し
2. **119行目**: LoadProperties()でアーティクルプロパティをロード
3. **122-124行目**: SMOでソーステーブルを取得
4. **136-139行目**: 垂直パーティショニング無効時の全列取得
5. **144-165行目**: 垂直パーティショニング有効時のsysarticlecolumnsクエリ
6. **172-187行目**: メタデータ追加と出力

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaReplArticle.ps1 | `public/Get-DbaReplArticle.ps1` | アーティクル取得 |
| 3-2 | Invoke-DbaQuery | - | SQLクエリ実行 |

### プログラム呼び出し階層図

```
Get-DbaReplArticleColumn
    │
    ├─ Get-DbaReplArticle
    │      ├─ Add-ReplicationLibrary
    │      ├─ Connect-DbaInstance
    │      └─ Get-DbaReplPublication
    │
    ├─ Article.LoadProperties()
    │
    ├─ Server.Databases[].Tables[] (SMO)
    │
    └─ Invoke-DbaQuery (VerticalPartition=true時)
```

### データフロー図

```
[入力]                          [処理]                                    [出力]

SqlInstance ──────────────────▶ Get-DbaReplArticle ───────────────────▶ Articles
                                      │
                               LoadProperties()
                                      │
                               SMOでテーブル取得
                                      │
                               VerticalPartition判定
                                      │
                    ┌─────────────────┴─────────────────┐
                    │                                   │
              全列取得                        sysarticlecolumnsクエリ
                    │                                   │
                    └─────────────────┬─────────────────┘
                                      │
Column ───────────────────────▶ 列フィルタリング
                                      │
                               メタデータ追加
                                      │
                               Select-DefaultView
                                      │
                                      ▼
                               列情報オブジェクト（8プロパティ）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaReplArticleColumn.ps1 | `public/Get-DbaReplArticleColumn.ps1` | ソース | メインコマンドレット実装 |
| Get-DbaReplArticle.ps1 | `public/Get-DbaReplArticle.ps1` | ソース | アーティクル取得 |
| Get-DbaReplArticleColumn.Tests.ps1 | `tests/Get-DbaReplArticleColumn.Tests.ps1` | テスト | ユニットテスト |
