使い慣れたツールで気象データを取得

接続を始める

必要なのはGribStreamのAPIトークンと、MySQL互換のクライアントまたはライブラリだけです。

1. 無料のAPIトークンを作成するか、既存のトークンを使います。
2. ユーザー名にはgribstream、パスワードにはAPIトークンを指定します。
3. gfsなどのデータセットをデータベースとして選択し、接続します。

mysql --host=mysql.gribstream.com \
  --port=3307 \
  --user=gribstream \
  --password \
  --database=gfs \
  --quick

MySQLコマンドラインクライアントではトークンの入力が求められるため、シェル履歴には残りません。このコマンドの--quickは、結果全体を待たず、到着した行から表示するための指定です。他のクライアントでは、結果を順次読み取る設定が異なります。

MySQLクエリはHTTP APIのクエリと同じAPIトークンとクォータを使います。使用量は、クエリに答えるために読み取った気象データに基づきます。データセット選びに迷った場合はモデルカタログを確認してください。全球データではgfsが分かりやすい出発点です。

MySQLを使う理由

MySQLドライバを備えた言語やツールなら、使い慣れた接続方法でGribStreamを検索できます。MySQLサーバーの運用、気象ファイルのインポート、新しいクライアントライブラリの習得は不要です。

この接続は読み取り専用で、気象データの検索に特化しています。データセットはデータベースとして表示され、気象フィールドを探索でき、未対応のSQLには明確なエラーが返ります。

気象列を探してクエリする

GribStreamの各気象パラメータは、データセット固有のMySQL列として公開されています。データセットを選んだら、クエリを書く前に利用できる列を確認してください。

SHOW FULL COLUMNS FROM gfs.timeseries;

結果から必要なFieldの値をコピーします。Commentには、読みやすい名称、元の単位、対応する正確なGS_VALUE(...)が表示されます。GFSの地上2 m気温なら、列名はtmp_2_m_above_groundです。

次の3つは同じ気象パラメータを表します。通常は気象列を使うのが最も簡単です。既存のHTTP APIクエリを変換するときやセレクタを動的に選ぶときは、正確なセレクタを指定できるGS_VALUEを使えます。JSON形式はモデルページに表示されるセレクタです。

tmp_2_m_above_ground

GS_VALUE(
  'TMP',
  '2 m above ground',
  ''
)

{
  "name": "TMP",
  "level": "2 m above ground",
  "info": ""
}

気象列名は自分で組み立てず、SHOW FULL COLUMNSまたはgribstream.selector_columnsからコピーしてください。多くは読みやすい名前ですが、長い名前や重複する名前には一定の規則で接尾辞が付きます。正確なセレクタ文字列では大文字と小文字が区別されます。

次のクエリは、1地点におけるGFSの地上2 m気温を今後6時間分返します。

SELECT forecasted_time,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time BETWEEN NOW() AND NOW() + INTERVAL 6 HOUR
  AND lat = 40.758
  AND lon = -73.985
  AND lead_time BETWEEN '0h' AND '48h'
ORDER BY forecasted_time
LIMIT 100;

この気象列の値はケルビンで公開されています。列名や別名から推測せず、Commentまたはカタログで単位を確認してください。

結果は通常の行です。次の値は説明用の例です。

forecasted_time       temp_k
2026-08-07 12:00:00   298.4
2026-08-07 13:00:00   299.1
2026-08-07 14:00:00   299.7

カタログで探す手順を使えば、パラメータ名から列を検索し、単位を確認し、必要に応じて正確なJSONセレクタやGS_VALUE式を取得できます。

接続時にgfsを選択済みならFROM timeseriesと書けます。未選択ならgfs.timeseriesのようにデータセットも指定します。

動作するクエリから始める

目的に最も近い例を開き、必要なデータセット、見つけた気象列、時刻、地点だけを変更してください。セレクタから列名を推測せず、SHOW FULL COLUMNSの列名をコピーします。

SELECT forecasted_time, name, lat, lon,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-13T06:00:00Z'
  AND (lat, lon, name) IN (
        (40.758, -73.985, 'Times Square'),
        (29.7604, -95.3698, 'Houston'),
        (51.5072, -0.1276, 'London')
      );

SELECT forecasted_time, lat, lon,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-13T06:00:00Z'
  AND lat BETWEEN 25 AND 50
  AND lon BETWEEN -125 AND -66
  AND grid_step = 1;

SELECT forecasted_time,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time IN (
        '2026-07-13T00:00:00Z',
        '2026-07-13T06:00:00Z',
        '2026-07-14T18:00:00Z'
      )
  AND lat = 40.758
  AND lon = -73.985;

SELECT forecasted_at, forecasted_time,
       tmp_2_m_above_ground AS temp_k
FROM gfs.runs
WHERE forecasted_at BETWEEN '2026-07-13T00:00:00Z'
                        AND '2026-07-13T12:00:00Z'
  AND lead_time BETWEEN '0h' AND '48h'
  AND lat = 40.758
  AND lon = -73.985
ORDER BY forecasted_at, forecasted_time;

SELECT forecasted_at, forecasted_time,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-14T00:00:00Z'
  AND forecasted_at <= '2026-07-12T18:00:00Z'
  AND lat = 40.758
  AND lon = -73.985
ORDER BY forecasted_time;

SELECT forecasted_time, member,
       tmp_2_m_above_ground AS temp_k
FROM gefsatmos.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-13T12:00:00Z'
  AND member IN (0, 1, 2)
  AND lead_time BETWEEN '0h' AND '48h'
  AND lat = 40.758
  AND lon = -73.985;

SELECT forecasted_time,
       tmp_2_m_above_ground AS temp_k,
       temp_k - 273.15 AS temp_c
FROM gfs.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-14T00:00:00Z'
  AND lat = 40.758
  AND lon = -73.985
  AND temp_c BETWEEN 18 AND 24;

SELECT forecasted_time, lat, lon,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time = '2026-07-13T18:00:00Z'
  AND lat BETWEEN 25 AND 50
  AND lon BETWEEN -125 AND -66
  AND grid_step = 0.5
ORDER BY temp_k DESC
LIMIT 20;

利用言語から接続する

以下から言語を選んでください。各例は安全に接続し、同じ小さな気象クエリを実行して行を読み取ります。トークンは環境変数またはシークレット管理サービスに保存し、接続文字列をコードに含めないでください。

mysql \
  -h mysql.gribstream.com -P 3307 \
  -u gribstream -p -D gfs \
  --quick

import os
import certifi
import pandas as pd
from sqlalchemy import URL, create_engine

url = URL.create(
    "mysql+mysqlconnector",
    username="gribstream",
    password=os.environ["GRIBSTREAM_API_TOKEN"],
    host="mysql.gribstream.com",
    port=3307,
    database="gfs",
)

engine = create_engine(url, connect_args={
    "ssl_verify_cert": True,
    "ssl_verify_identity": True,
    "ssl_ca": certifi.where(),
})

sql = """
SELECT forecasted_time,
       tmp_2_m_above_ground AS temp_k
FROM timeseries
WHERE forecasted_time BETWEEN NOW() AND NOW() + INTERVAL 6 HOUR
  AND lat = 40.758 AND lon = -73.985
ORDER BY forecasted_time
"""

for frame in pd.read_sql_query(sql, engine, chunksize=10_000):
    print(frame.head())

String SQL = """
    SELECT forecasted_time,
           tmp_2_m_above_ground AS temp_k
    FROM timeseries
    WHERE forecasted_time BETWEEN NOW() AND NOW() + INTERVAL 6 HOUR
      AND lat = 40.758 AND lon = -73.985
    ORDER BY forecasted_time
    """;

String url = "jdbc:mysql://mysql.gribstream.com:3307/gfs?sslMode=VERIFY_IDENTITY";
Properties props = new Properties();
props.setProperty("user", "gribstream");
props.setProperty("password", System.getenv("GRIBSTREAM_API_TOKEN"));

try (Connection db = DriverManager.getConnection(url, props);
     Statement statement = db.createStatement(
         ResultSet.TYPE_FORWARD_ONLY,
         ResultSet.CONCUR_READ_ONLY)) {
    statement.setFetchSize(Integer.MIN_VALUE);
    try (ResultSet rows = statement.executeQuery(SQL)) {
        while (rows.next()) {
            System.out.println(rows.getTimestamp("forecasted_time"));
        }
    }
}

const string SQL = @"
SELECT forecasted_time,
       tmp_2_m_above_ground AS temp_k
FROM timeseries
WHERE forecasted_time BETWEEN NOW() AND NOW() + INTERVAL 6 HOUR
  AND lat = 40.758 AND lon = -73.985
ORDER BY forecasted_time";

var builder = new MySqlConnectionStringBuilder {
    Server = "mysql.gribstream.com",
    Port = 3307,
    Database = "gfs",
    UserID = "gribstream",
    Password = Environment.GetEnvironmentVariable("GRIBSTREAM_API_TOKEN"),
    SslMode = MySqlSslMode.VerifyFull,
};

await using var db = new MySqlConnection(builder.ConnectionString);
await db.OpenAsync();
await using var command = new MySqlCommand(SQL, db);
await using var rows = await command.ExecuteReaderAsync(
    CommandBehavior.SequentialAccess);
while (await rows.ReadAsync()) {
    Console.WriteLine(rows.GetDateTime("forecasted_time"));
}

const query = `
SELECT forecasted_time,
       tmp_2_m_above_ground AS temp_k
FROM timeseries
WHERE forecasted_time BETWEEN NOW() AND NOW() + INTERVAL 6 HOUR
  AND lat = 40.758 AND lon = -73.985
ORDER BY forecasted_time`

cfg := mysql.NewConfig()
cfg.User = "gribstream"
cfg.Passwd = os.Getenv("GRIBSTREAM_API_TOKEN")
cfg.Net = "tcp"
cfg.Addr = "mysql.gribstream.com:3307"
cfg.DBName = "gfs"
cfg.TLSConfig = "true"
cfg.ParseTime = true
db, err := sql.Open("mysql", cfg.FormatDSN())
if err != nil { log.Fatal(err) }
defer db.Close()

rows, err := db.QueryContext(ctx, query)
if err != nil { log.Fatal(err) }
defer rows.Close()
for rows.Next() {
    var validTime time.Time
    var tempK float64
    if err := rows.Scan(&validTime, &tempK); err != nil { log.Fatal(err) }
}

import mysql from 'mysql2';

const SQL = `
SELECT forecasted_time,
       tmp_2_m_above_ground AS temp_k
FROM timeseries
WHERE forecasted_time BETWEEN NOW() AND NOW() + INTERVAL 6 HOUR
  AND lat = 40.758 AND lon = -73.985
ORDER BY forecasted_time`;

const db = mysql.createConnection({
  host: 'mysql.gribstream.com',
  port: 3307,
  user: 'gribstream',
  password: process.env.GRIBSTREAM_API_TOKEN,
  database: 'gfs',
  ssl: {},
});

db.query(SQL)
  .stream({ highWaterMark: 64 })
  .on('data', row => console.log(row.forecasted_time))
  .on('error', err => { throw err; })
  .on('end', () => db.end());

use mysql::{OptsBuilder, Pool, SslOpts};
use mysql::prelude::Queryable;

let sql = r#"
SELECT forecasted_time,
       tmp_2_m_above_ground AS temp_k
FROM timeseries
WHERE forecasted_time BETWEEN NOW() AND NOW() + INTERVAL 6 HOUR
  AND lat = 40.758 AND lon = -73.985
ORDER BY forecasted_time"#;

let opts = OptsBuilder::new()
    .ip_or_hostname(Some("mysql.gribstream.com"))
    .tcp_port(3307)
    .user(Some("gribstream"))
    .pass(std::env::var("GRIBSTREAM_API_TOKEN").ok())
    .db_name(Some("gfs"))
    .ssl_opts(Some(SslOpts::default()));

let pool = Pool::new(opts)?;
let mut db = pool.get_conn()?;
let rows = db.query_iter(sql)?;
for row in rows {
    println!("{:?}", row?);
}

const char *sql =
    "SELECT forecasted_time, "
    "tmp_2_m_above_ground AS temp_k "
    "FROM timeseries "
    "WHERE forecasted_time BETWEEN NOW() AND NOW() + INTERVAL 6 HOUR "
    "AND lat = 40.758 AND lon = -73.985 "
    "ORDER BY forecasted_time";

MYSQL *db = mysql_init(NULL);
unsigned int ssl_mode = SSL_MODE_VERIFY_IDENTITY;
mysql_options(db, MYSQL_OPT_SSL_MODE, &ssl_mode);

mysql_real_connect(db, "mysql.gribstream.com", "gribstream",
    getenv("GRIBSTREAM_API_TOKEN"), "gfs", 3307, NULL, 0);
mysql_query(db, sql);
MYSQL_RES *result = mysql_use_result(db);
MYSQL_ROW row;
while ((row = mysql_fetch_row(result)) != NULL) {
    printf("%s\n", row[0]);
}
mysql_free_result(result);
mysql_close(db);

export MYSQL_HOST=mysql.gribstream.com
export MYSQL_TCP_PORT=3307
export MYSQL_USER=gribstream
export MYSQL_PWD="$GRIBSTREAM_API_TOKEN"
export MYSQL_DATABASE=gfs

ATTACH 'ssl_mode=verify_identity' AS gribstream_db
  (TYPE mysql, READ_ONLY);

SELECT forecasted_time, lead_time, lat, lon,
       tmp_2_m_above_ground AS temp_k
FROM gribstream_db.gfs.timeseries
WHERE forecasted_time BETWEEN CURRENT_TIMESTAMP
                          AND CURRENT_TIMESTAMP + INTERVAL 6 HOUR
  AND lat = 40.758
  AND lon = -73.985
  AND lead_time BETWEEN 0 AND 48
LIMIT 100;

SELECT *
FROM mysql_query('gribstream_db', $sql$
  SELECT forecasted_time, name, lat, lon,
         tmp_2_m_above_ground AS temp_k
  FROM gfs.timeseries
  WHERE forecasted_time BETWEEN NOW() AND NOW() + INTERVAL 6 HOUR
    AND (lat, lon, name) IN (
          (40.758, -73.985, 'Times Square'),
          (29.7604, -95.3698, 'Houston')
        )
    AND lead_time BETWEEN '0h' AND '48h'
  LIMIT 100
$sql$);

大きな結果には、ドライバの行イテレータ、ストリーミングモード、または同等の機能を使い、結果全体をメモリへ蓄積しないようにしてください。

timeseriesとrunsの選び方

各データセットのスキーマには、同じ2種類の気象テーブルがあります。返したい列ではなく、答えたい問いに合わせてテーブルを選びます。

forecasted_atはモデル実行時刻、forecasted_timeは予報対象の有効時刻です。lead_timeは両者の差を時間単位で表し、結果列として選択することも条件に使うこともできます。

SELECT forecasted_at, forecasted_time, lat, lon,
       tmp_2_m_above_ground AS temp_k
FROM gfs.runs
WHERE forecasted_at BETWEEN '2026-07-13T00:00:00Z'
                        AND '2026-07-13T12:00:00Z'
  AND lead_time BETWEEN '0h' AND '48h'
  AND lat = 40.758
  AND lon = -73.985
ORDER BY forecasted_at DESC, forecasted_time ASC;

SELECT forecasted_at, forecasted_time, index_updated_at,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-13T06:00:00Z'
  AND lat = 40.758
  AND lon = -73.985
ORDER BY forecasted_time;

データセット、気象列、正確なセレクタを探す

列名、パラメータのレベル、単位を推測しないでください。データセットを見つけて気象列を確認し、API形式やGS_VALUEによる正確な指定が必要な場合だけセレクタの対応表を使います。

1. データセットを探す

SELECT code, full_name, provider, min_lead_time, max_lead_time,
       is_ensemble, member_count, members, parameter_count
FROM gribstream.datasets
WHERE code LIKE '%gfs%'
ORDER BY code;

SELECT code, archive_start, archive_window, rolling_window,
       time_resolution, run_cadence, min_lead_time, max_lead_time,
       catalog_updated_at
FROM gribstream.datasets
WHERE code = 'gfs';

2. 気象列を確認する

SHOW FULL COLUMNS FROM gfs.timeseries LIKE '%tmp%';

3. 対応表を検索するか、正確なセレクタを使う

SELECT short_name, full_name, units, has_code_table, variation_count
FROM gribstream.parameters
WHERE dataset = 'gfs'
  AND (short_name = 'TMP' OR full_name LIKE '%temperature%')
ORDER BY short_name
LIMIT 20;

SELECT column_name, full_name, units, name, level, info,
       selector_json, gs_value_sql
FROM gribstream.selector_columns
WHERE dataset = 'gfs'
  AND column_name = 'tmp_2_m_above_ground';

gribstream.selector_columnsでは、各気象列に対応する読みやすい名称、単位、JSONセレクタ、同等のGS_VALUE式を確認できます。クエリにはdatasetの完全一致条件が必要です。

通常のSQLでは生成済みのcolumn_nameを使います。APIセレクタをそのままSQLへ置き換える場合はGS_VALUE(name, level, info)を使います。このgefsatmosmeanセレクタはinfoが空ではないため、3つすべての引数が必要です。

{
  "name": "CAPE",
  "level": "surface",
  "info": "ens mean"
}

GS_VALUE(
  'CAPE',
  'surface',
  'ens mean'
)

モデルページには引き続き標準のJSONセレクタと、対応する正確なGS_VALUE式が表示されます。SQL列名は、重複や長い識別子が解決済みの現在のスキーマからコピーしてください。

4. データセット間で比較できる気象要素を探す

共有パラメータには、共通の気象概念、出力単位、対応するデータセットが一覧表示されます。モデルを比較する前にこのカタログを使い、その後で各データセットの正確なセレクタを特定してください。セレクタ名が同じとは限りません。

SELECT code, label, units, supported_datasets
FROM gribstream.shared_parameters
WHERE code = 'temperature_2m';

SELECT forecasted_time,
       v_10u_sfc AS u_component,
       v_10v_sfc AS v_component,
       func.Hypot(u_component, v_component) AS wind_speed
FROM ifsoper.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-13T06:00:00Z'
  AND lat = 48.8566
  AND lon = 2.3522
ORDER BY forecasted_time;

SELECT topic, supported_syntax, example, notes
FROM gribstream.sql_dialect
ORDER BY topic;

SELECT name, description, `sql`
FROM gribstream.query_examples
ORDER BY name;

SHOW FULL COLUMNS FROM gfs.timeseries;

値、計算、フィルタ

計算列には一般的なSQL式を使い、SELECTリストの前方で定義した別名も参照できます。まず気象列に別名を付け、その別名を後続の式で使います。単位変換は明示的に記述してください。

SELECT forecasted_time,
       tmp_2_m_above_ground AS temp_k,
       temp_k - 273.15 AS temp_c
FROM gfs.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-13T12:00:00Z'
  AND lat = 40.758
  AND lon = -73.985
  AND (temp_c BETWEEN 18 AND 30 OR temp_c IS NULL);

気象値の条件ではBETWEEN、数値のIN、NULL判定、括弧、NOT、ブール条件の組み合わせを利用できます。時刻、地点、リードタイム、メンバー、モデル実行の条件はANDで結び、ORは気象値の条件内だけで使います。

SELECT forecasted_time,
       ugrd_10_m_above_ground AS u,
       vgrd_10_m_above_ground AS v,
       func.Hypot(u, v) AS wind_speed
FROM gfs.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-13T12:00:00Z'
  AND lat = 40.758
  AND lon = -73.985
  AND wind_speed > 5;

SELECT forecasted_time AS valid_time,
       GS_VALUE(?, ?) AS temp_k,
       temp_k - ? AS temp_c
FROM gfs.timeseries
WHERE forecasted_time BETWEEN ? AND ?
  AND lat = ?
  AND lon = ?
  AND temp_c BETWEEN ? AND ?
LIMIT 100;

SELECT DISTINCT name,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-13T06:00:00Z'
  AND (lat, lon, name) IN (
        (40.758, -73.985, 'Times Square'),
        (29.7604, -95.3698, 'Houston')
      )
LIMIT 100;

時間範囲、相対時刻、タイムゾーン

timeseries.forecasted_timeは有効時刻、runs.forecasted_atはモデル実行時刻です。範囲には両方の境界が必要で、BETWEENでは両端を含みます。

隣接する期間には、forecasted_time >= start AND forecasted_time < endのような半開区間を推奨します。連続したクエリを結合したとき、境界の時刻が重複しません。

SELECT forecasted_at, forecasted_time,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time BETWEEN NOW() - INTERVAL 2 DAY AND NOW()
  AND forecasted_at <= NOW() - INTERVAL 6 HOUR
  AND lat = 40.758
  AND lon = -73.985
LIMIT 100;

SELECT forecasted_time,
       CONVERT_TZ(forecasted_time, 'UTC', 'Europe/Paris') AS paris_time,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time >=
        CONVERT_TZ('2026-10-25 00:00:00', 'Europe/Paris', 'UTC')
  AND forecasted_time <
        CONVERT_TZ('2026-10-26 00:00:00', 'Europe/Paris', 'UTC')
  AND lat = 48.8566
  AND lon = 2.3522
LIMIT 100;

地点、格子、リードタイム、アンサンブル

1地点には1組の座標、複数の名前付き地点には座標の組のリスト、規則的な格子には緯度・経度の範囲とgrid_stepを使います。それぞれの完全な例はクエリ例にあります。

• 1地点：lat = value AND lon = valueを使います。
• 複数地点：(lat, lon)または(lat, lon, name)をINとともに使います。
• 格子：緯度と経度の両方を範囲指定し、度単位のgrid_stepを設定します。間隔を小さくすると地点数とクォータ消費が増えます。

効率のよいクエリにする

クォータ使用量は、返された行数ではなく、クエリの評価に読み取った気象データに基づきます。temp_c > 30のような気象値や計算済みの別名に対する条件は、その値を読み取った後でのみ結果から行を除外できます。そのため値のフィルタで返る行がごく少なくても、大きなクエリは多くのクォータを消費することがあります。

有効時刻、地点、リードタイム、アンサンブルメンバーの条件は、選択するデータ量を減らします。特に効果が大きいのは次の点です。

• 複数のモデル実行履歴が必要な場合を除き、timeseriesを使います。
• 時間範囲を短くするか、正確な時刻のリストを使います。
• 必要な気象パラメータ列だけを選びます。
• 広い格子より正確な地点を優先し、格子を使う場合は適切なgrid_stepを選びます。
• lead_timeを制限し、必要なアンサンブルメンバーだけを選びます。

探索時に並べ替えを使う

ORDER BYは主に対話的な操作やデータ探索向けです。多少の追加処理より、すぐに読める結果を優先するときに使います。範囲が限定されたクエリでは、主要な時刻列を最初のキーにすると、通常は行を順次返せます。timeseriesではforecasted_time、runsではforecasted_atを使い、昇順または降順を選びます。必要なら、選択した列や別名を第2キー以降に追加できます。

SELECT forecasted_time AS valid_time, name, lat, lon,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-13T12:00:00Z'
  AND (lat, lon, name) IN (
        (40.758, -73.985, 'Times Square'),
        (29.7604, -95.3698, 'Houston'),
        (51.5072, -0.1276, 'London')
      )
ORDER BY valid_time DESC, temp_k DESC, name ASC;

runsでは、forecasted_atを最初にし、lead_timeの両端を制限します。安全に処理できないほど大きな並べ替え結果になる場合は、選択範囲を狭めるかORDER BYを外し、アプリケーション側で並べ替えてください。

バックフィルなど大量のデータを取得するときはORDER BYを省略してください。順序が必要なら、受信後に並べ替えます。広い選択範囲と気象値のフィルタを組み合わせる場合は特に、サーバー側の並べ替えが処理速度の制約になるのを避けられます。

LIMITは結果の大きさに使い、クォータ制限には使わない

LIMITは対話的な出力を小さく保つのに便利ですが、読み取る気象データ量は決めません。フィルタや並べ替えでは、最終結果よりはるかに多くのデータを読むことがあります。クォータ使用量を減らすには、上記の選択条件を使ってください。

高度な機能：EXPLAINでクエリを検証

ほとんどのクエリにEXPLAINは必要ありません。気象クエリの先頭に付けると、気象データの行を取得せず、クエリのクォータも消費せずに、ステートメントを検証して診断情報を確認できます。主にトラブルシューティングやサポートで利用します。

EXPLAIN
SELECT forecasted_time, lat, lon,
       tmp_2_m_above_ground AS temp_k
FROM gfs.timeseries
WHERE forecasted_time BETWEEN '2026-07-13T00:00:00Z'
                          AND '2026-07-13T12:00:00Z'
  AND (lat, lon) = (40.758, -73.985)
LIMIT 100;

ストリーミング、キャンセル、エラー

行は順次利用可能になります。すぐに表示されるかどうかはMySQLクライアントやライブラリによるため、大きなクエリには非バッファ、ストリーミング、反復、または分割読み取りのインターフェースを使ってください。設定はクライアントごとに異なります。各ライブラリの資料はクライアントリファレンスから参照できます。

• クライアントの切断：接続を閉じると、実行中のクエリがキャンセルされます。
• MySQL CLI：Ctrl+Cで実行中のクエリを停止します。

トラブルシューティング

SHOW SESSION STATUS LIKE 'Compression%';

AIエージェント向けの自己記述型ツールとして使う

MCPツールとして提供されるものを含め、汎用のMySQLデータベースコネクタからmysql.gribstream.com:3307へ接続できます。コネクタのシークレット設定を通じてAPIトークンを渡してください。

以下の手順ファイルをエージェントへ渡してください。スキーマとカタログテーブルから、データセット、気象列、単位、正確なセレクタの対応、SQL方言の規則、実行可能な例を調べてからクエリを組み立てられます。

1. gribstream.sql_dialectとgribstream.query_examplesを読みます。
2. gribstream.datasetsを検索し、選んだ気象テーブルにSHOW FULL COLUMNSを実行します。
3. 正確なJSONセレクタまたはGS_VALUEとの対応が必要な場合は、gribstream.selector_columnsを使います。
4. 質問に答えられる、最小限で範囲の限られたクエリを組み立てて実行します。
5. EXPLAINはクエリの検証または問題調査にだけ使います。

完全な手順、構文の制限、データ取得のルールをまとめたGribStream MySQLエージェント向けスキルをダウンロードできます。

対応するSQLと意図的な制限

この制限により、意外な動作をするSQLを受け入れるのではなく、クエリの予測可能性、結果の順次読み取り、エラーの明確さを保ちます。

付録：クライアント設定リファレンス

TLS、圧縮、結果のバッファリング、キャンセル、タイムアウト、接続プールはSQLではなくクライアントまたはドライバで設定します。実際に接続に使うライブラリのドキュメントを参照してください。