data-upload-java-cli

Domo データアップロードガイド

推奨戦略 — まず JSON コネクターを使用し、失敗した場合は CLI にフォールバック： データソースが REST／JSON API の場合は、必ず最初に Domo JSON No-Code Connector（domo-json-no-code-connector スキル）をお試しください。これにより Domo 内にライブで再実行可能なコネクターストリームが作成され、スクリプトを再実行しなくても UI からデータを更新できます。 Java CLI にフォールバックするのは、次の場合に限ります。

• JSON コネクターが失敗した場合（認証の問題、未対応のページネーション、解析エラーなど）
• データがすでに CSV 形式（ローカルファイル、データベースのエクスポートなど）で、接続先のソース API がない場合

概要

このガイドでは、domoutil.jar を使用して CSV データを Domo にアップロードする Java CLI のフォールバック方法を説明します。CLI はスキーマの導出、データセットの作成、分割アップロード、インデックス作成を自動的に処理します。

JSON コネクターを優先し、CLI にフォールバックするパターン

REST／JSON API から Domo にデータを取得する場合は、コードで次の 2 経路の戦略を使用します。

def ingest_object(obj_type, cfg):
    # Path 1 — JSON No-Code Connector (creates a live stream in Domo)
    ok, dataset_id = try_json_connector(obj_type, cfg)

    # Path 2 — CLI fallback (fetch → CSV → upload)
    if not ok:
        ok, dataset_id = try_cli_fallback(obj_type, cfg, work_dir)

経路 1（JSON コネクター）の手順：

1. POST /api/data/v1/accounts — 認証用の json5 アカウントを作成します
2. POST /api/data/v1/streams — URL、ヘッダー、解析、ページングを設定します
3. POST /api/data/v1/streams/{id}/executions — 実行を開始します
4. currentState が "SUCCESS" または "ERROR" になるまで、GET /api/data/v1/streams/{id}/executions/{execId} をポーリングします
5. "ERROR" または各ステップで HTTP エラーが発生した場合は、経路 2 に進みます

経路 2（CLI へのフォールバック）の手順：

1. requests を使用してソース API からすべてのページを取得します
2. レコードを CSV ファイルに書き込みます
3. derive-schema → スキーマ JSON を作成します
4. create-dataset → データセット UUID を取得します
5. upload-dataset -h → CSV をアップロードします

CLI に直接進む場合：

• データがすでに CSV 形式である（ソース API がない）
• ソース API が JSON／REST ではない（SOAP、バイナリなど）
• JSON コネクターがソースのページネーションに対応できないことをすでに確認している

JSON コネクターの認証に関する注意： authentication: "none" とともに credentialsType: "fields" を使用し、jsonSelection.httpsHeaders に Authorization ヘッダーを直接設定します。authType は使用しないでください。json5 では無効であり、400 エラーが返されます。

Java CLI（フォールバック経路）

• CLI の場所： /Users/elliottleonard/Documents/Cursor/CLI/domoutil.jar
• 実行コマンド： java -jar /Users/elliottleonard/Documents/Cursor/CLI/domoutil.jar

前提条件

• Java がインストールされていること
• Domo アクセストークン（形式：DDCI...）
• Domo インスタンスの URL（例：instance.domo.com）
• アップロードする CSV ファイル（RFC 4180 準拠）

クイックリファレンス

接続

connect -server <instance>.domo.com -token <API_TOKEN>

whoami で確認します。

ワークフロー全体

ステップ 1：CSV からスキーマを導出する

derive-schema -d /path/to/data.csv -r 500

• -d：CSV ファイルのパス
• -r：型の検出に使用するサンプル行数（既定値として 500 が適しています）
• 列名と検出された型（STRING、LONG、DOUBLE、DATETIME など）を返します

出力形式：

Schema:
  column_name1         STRING
  column_name2         LONG
  column_name3         DATETIME

ステップ 2：スキーマ JSON ファイルを作成する

derive-schema の出力を JSON スキーマファイルに変換します。

{
  "columns": [
    {
      "name": "column_name1",
      "type": "STRING",
      "metadata": null,
      "upsertKey": false
    },
    {
      "name": "column_name2",
      "type": "LONG",
      "metadata": null,
      "upsertKey": false
    },
    {
      "name": "column_name3",
      "type": "DATETIME",
      "metadata": null,
      "upsertKey": false
    }
  ],
  "objects": []
}

有効な列型： STRING、LONG、DOUBLE、DECIMAL、DATETIME、DATE

ステップ 3：Domo にデータセットを作成する

create-dataset -n "<Dataset Name>" -t "<type>" -s /path/to/schema.json

• -n：データセット名（Domo に表示されます）
• -t：データセットの種類（汎用の種類として "domo-cli" を使用します）
• -s：スキーマ JSON ファイルのパス

出力：

Created DataSet: <dataset-uuid>

この UUID を保存してください。アップロードの手順で必要になります。

ステップ 4：CSV データをアップロードする

upload-dataset -i <dataset-uuid> -f /path/to/data.csv -h

• -i／--id：作成手順で取得したデータセット UUID
• -f／--data：CSV ファイルのパス
• -h／--headers：CSV にヘッダー行がある場合に必須です（先頭行をスキップします）

成功時の出力：

Started upload for DataSet <uuid>.
Finished upload for DataSet <uuid>. Bytes sent X.
Started indexing for dataset <uuid>
Finished indexing for dataset <uuid> with status SUCCESS
Data uploaded successfully

アップロードオプション

フラグ	説明
-i <ID>	データセット UUID（必須）
-f <FILE>	CSV ファイルのパス
-h	CSV にヘッダー行がある
-a／--append	既存のデータを置き換えずに追加する
-d <DIR>	ディレクトリ内のすべての CSV をアップロードします（ファイルにヘッダーを含めないでください）
-c	ファイルが gzip 圧縮されている（-d と併用する場合のみ）
-p <TAG>	パーティションタグ（--append と併用する場合のみ）
-m <N>	アップロードスレッドの最大数
-x	アップロード後のインデックス作成をスキップする

スクリプト／非対話モード

自動化のため、コマンドを標準入力経由でパイプします。

echo -e "connect -server instance.domo.com -token YOUR_TOKEN\nupload-dataset -i <uuid> -f data.csv -h\nquit" \
  | java -jar /Users/elliottleonard/Documents/Cursor/CLI/domoutil.jar

正常に終了するよう、必ず最後に quit を指定してください。

バッチアップロード：複数の CSV

Python スクリプトのパターン

複数の CSV ファイルを一度にアップロードする場合は、この方法を推奨します。スクリプトでは、次の処理を行います。

1. 各 CSV のスキーマを導出します
2. スキーマ JSON ファイルを作成します
3. Domo にデータセットを作成します
4. CSV データをアップロードします

import subprocess, json, os, re

csv_dir = "/path/to/csv/directory"
cli = "/Users/elliottleonard/Documents/Cursor/CLI/domoutil.jar"
server = "instance.domo.com"
token = "DDCI..."
schema_dir = "/tmp/domo_schemas"
os.makedirs(schema_dir, exist_ok=True)

csvs = sorted([f for f in os.listdir(csv_dir) if f.endswith('.csv')])

# --- Phase 1: Derive schemas and save as JSON ---
for csv_file in csvs:
    csv_path = os.path.join(csv_dir, csv_file)
    cmds = f"connect -server {server} -token {token}\nderive-schema -d {csv_path} -r 500\nquit"
    result = subprocess.run(['java', '-jar', cli], input=cmds, capture_output=True, text=True, timeout=60)

    columns = []
    in_schema = False
    for line in result.stdout.split('\n'):
        if 'Schema:' in line:
            in_schema = True
            continue
        if in_schema and line.startswith('  ') and line.strip():
            parts = line.split()
            if len(parts) >= 2:
                col_type = parts[-1]
                col_name = ' '.join(parts[:-1]).strip()
                columns.append({"name": col_name, "type": col_type, "metadata": None, "upsertKey": False})
        elif in_schema and line.startswith('>'):
            in_schema = False

    schema = {"columns": columns, "objects": []}
    schema_path = os.path.join(schema_dir, csv_file.replace('.csv', '.json'))
    with open(schema_path, 'w') as f:
        json.dump(schema, f, indent=2)

# --- Phase 2: Create datasets ---
cmds = [f"connect -server {server} -token {token}"]
for csv_file in csvs:
    schema_path = os.path.join(schema_dir, csv_file.replace('.csv', '.json'))
    # Generate a friendly name from the filename
    friendly_name = csv_file.replace('.csv', '').split('.')[-1].replace('_', ' ').title()
    cmds.append(f'create-dataset -n "{friendly_name}" -t "domo-cli" -s {schema_path}')
cmds.append("quit")

result = subprocess.run(['java', '-jar', cli], input='\n'.join(cmds), capture_output=True, text=True, timeout=120)

# Parse dataset IDs from output
dataset_ids = []
for line in result.stdout.split('\n'):
    match = re.search(r'Created DataSet: ([0-9a-f-]{36})', line)
    if match:
        dataset_ids.append(match.group(1))

# --- Phase 3: Upload data ---
cmds = [f"connect -server {server} -token {token}"]
for csv_file, dataset_id in zip(csvs, dataset_ids):
    csv_path = os.path.join(csv_dir, csv_file)
    cmds.append(f'upload-dataset -i {dataset_id} -f {csv_path} -h')
cmds.append("quit")

result = subprocess.run(['java', '-jar', cli], input='\n'.join(cmds), capture_output=True, text=True, timeout=600)
print(result.stdout)

シェルのみのパターン

よりシンプルなケースでは、シェルスクリプトを使用します。

CLI="/Users/elliottleonard/Documents/Cursor/CLI/domoutil.jar"
SERVER="instance.domo.com"
TOKEN="DDCI..."

# Create commands file
cat > /tmp/upload_cmds.txt << EOF
connect -server $SERVER -token $TOKEN
upload-dataset -i <dataset-id-1> -f /path/to/file1.csv -h
upload-dataset -i <dataset-id-2> -f /path/to/file2.csv -h
quit
EOF

cat /tmp/upload_cmds.txt | java -jar "$CLI"

既存のデータセットのデータを置き換える

既存のデータセットのすべてのデータを置き換える（追加ではない）には、--append を指定せずに同じ upload-dataset コマンドを使用します。

upload-dataset -i <existing-dataset-uuid> -f /path/to/new_data.csv -h

これにより、全件置換が実行されます。既存のすべての行が削除され、新しい CSV データに置き換えられます。

データを追加する

既存のデータセットのデータを削除せずに行を追加するには、次のようにします。

upload-dataset -i <dataset-uuid> -f /path/to/new_rows.csv -h --append

よくある落とし穴

1. -h フラグの指定漏れ

CSV にヘッダー行がある場合に -h を指定し忘れると、ヘッダー行がデータとしてインポートされます。ヘッダー付きの CSV では、必ず -h を使用してください。

2. upload-dataset には既存のデータセットが必要

upload-dataset コマンドはデータセットを作成しません。先にスキーマファイルを使って create-dataset を実行し、返された UUID を使ってから upload-dataset を実行する必要があります。有効な --id を指定せずにアップロードすると、次のエラーが発生します。

Executing POST: https://.../datasources/null/uploads
An error occurred while uploading the data from file

3. スキーマの列名は CSV のヘッダーと一致させる必要があります

スキーマ JSON の列名は、CSV のヘッダー名と完全に一致している必要があります（大文字と小文字は区別されます）。自動検出するには derive-schema を使用してください。

4. create-dataset には -t フラグが必須

データセットタイプ（-t）は必須です。安全なデフォルト値として "domo-cli" を使用してください。

create-dataset -n "My Dataset" -t "domo-cli" -s schema.json

5. 大きなファイルは自動的に分割されます

約 10MB を超えるファイルは、複数のアップロードパートに自動的に分割されます。CLI が透過的に処理します。非常に大きなファイルをアップロードする場合は、-m を使ってスレッド数を制御することを検討してください。

6. derive-schema による最初の列の解析

derive-schema の出力では、最初の列名が前のテキストと連結される場合があります。必ず最初の列名を CSV のヘッダーと照合してください。

7. ディレクトリのアップロードではヘッダーは不要です

-d（ディレクトリのアップロード）を使用する場合、CSV ファイルにヘッダー行を含めないでください。このモードは、事前に分割されたパーティションデータ向けに設計されています。

アップロードの確認

アップロード後、データにアクセスできることを確認します。

query-data -id <dataset-uuid> -q "SELECT * FROM table LIMIT 10"

または、データセットのメタデータを確認します。

get-dataset -id <dataset-uuid>
get-schema -id <dataset-uuid>