Interroga i dati meteo con gli strumenti che usi già

Inizia qui

Ti servono soltanto un token API GribStream e un client o una libreria compatibile con MySQL.

1. Crea un token API gratuito oppure usane uno esistente.
2. Usa gribstream come nome utente e il token API come password.
3. Seleziona un dataset, per esempio gfs, come database e connettiti.

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

Il client a riga di comando MySQL richiede il token senza inserirlo nella cronologia della shell. In questo comando, --quick indica al client di stampare le righe appena arrivano invece di attendere il risultato completo. Gli altri client usano impostazioni diverse per i risultati incrementali.

Le query MySQL usano lo stesso token API e la stessa quota delle query API HTTP. L'utilizzo dipende dai dati meteo letti per rispondere alla query. Se non sai quale dataset scegliere, consulta il catalogo dei modelli; gfs è un buon punto di partenza globale.

Perché MySQL?

I linguaggi e gli strumenti dotati di un driver MySQL possono usare questa connessione familiare per interrogare GribStream. Non devi gestire un server MySQL, importare file meteo né imparare una nuova libreria client.

La connessione è di sola lettura e pensata appositamente per i dati meteo. I dataset appaiono come database, i campi meteo sono esplorabili e la sintassi SQL non supportata restituisce un errore chiaro.

Trova una colonna meteo e interrogala

Ogni parametro meteorologico di GribStream appare come una colonna MySQL specifica del dataset. Dopo aver scelto un dataset, esamina le sue colonne prima di scrivere la query:

SHOW FULL COLUMNS FROM gfs.timeseries;

Nel risultato, copia il valore Field che ti serve. Comment indica il nome leggibile, le unità native e l'equivalente esatto con GS_VALUE(...). Per la temperatura GFS a 2 m, la colonna è tmp_2_m_above_ground.

Queste tre forme identificano lo stesso parametro meteorologico. La colonna meteo è la forma SQL più semplice; GS_VALUE è l'alternativa con selettore esatto per tradurre una query esistente dell'API HTTP o scegliere dinamicamente il selettore. La forma JSON è il selettore mostrato nelle pagine dei modelli.

tmp_2_m_above_ground

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

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

Copia i nomi delle colonne meteo da SHOW FULL COLUMNS o gribstream.selector_columns invece di costruirli. La maggior parte è leggibile; i nomi lunghi o in collisione ricevono un suffisso deterministico. I selettori esatti distinguono maiuscole e minuscole.

Questa query restituisce le prossime sei ore di temperatura GFS a 2 m per un punto:

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;

Questa colonna meteo pubblica valori in kelvin. Controlla il suo Comment o il catalogo per conoscere le unità, invece di dedurle dal nome della colonna o dall'alias.

Il risultato è composto da normali righe. I valori seguenti sono illustrativi:

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

Usa il percorso di ricerca nel catalogo per cercare le colonne per nome del parametro, controllare le unità e recuperare il selettore JSON esatto o l'espressione GS_VALUE quando necessario.

Se la connessione ha già selezionato gfs, usa FROM timeseries. Altrimenti specifica la tabella come gfs.timeseries.

Parti da una query funzionante

Scegli l'esempio più vicino al tuo obiettivo, espandilo e modifica solo il dataset, la colonna meteo trovata, i tempi o i luoghi necessari. Copia i nomi da SHOW FULL COLUMNS invece di provare a dedurre come viene normalizzato un selettore.

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;

Connettiti dal tuo linguaggio

Scegli un linguaggio qui sotto. Ogni esempio stabilisce una connessione sicura, esegue la stessa piccola query meteo e ne legge le righe. Conserva il token in una variabile d'ambiente o in un gestore di segreti; non inserirlo mai in una stringa di connessione nel codice.

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$);

Per risultati grandi, usa l'iteratore di righe, la modalità streaming o l'equivalente del tuo driver, così non raccoglierà l'intero risultato in memoria.

Scegli timeseries o runs

Ogni schema di dataset espone le stesse due forme di tabella meteo. Scegli la tabella in base alla domanda a cui vuoi rispondere, non alle colonne che vuoi restituire.

forecasted_at è l'orario di inizializzazione del modello. forecasted_time è l'orario di validità della previsione. lead_time è la differenza tra i due in ore e può essere selezionato o filtrato.

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;

Scopri dataset, colonne meteo e selettori esatti

Non indovinare nomi delle colonne, livelli dei parametri o unità. Trova un dataset, esamina le sue colonne meteo e usa la mappatura del selettore esatto solo quando ti serve la forma dell'API o l'alternativa GS_VALUE.

1. Trova un dataset

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. Esplora le colonne meteo

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

3. Cerca le mappature o usa un selettore esatto

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 associa ogni colonna meteo al nome leggibile, alle unità, al selettore JSON e all'espressione GS_VALUE equivalente. La query richiede una condizione esatta su dataset.

Usa il column_name generato nel normale SQL. Usa GS_VALUE(name, level, info) quando ti serve la traduzione diretta di un selettore dell'API. Questo selettore di gefsatmosmean ha un valore info non vuoto, quindi sono necessari tutti e tre gli argomenti:

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

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

Le pagine dei modelli continuano a mostrare il selettore JSON canonico e la sua forma esatta con GS_VALUE. Copia i nomi delle colonne SQL dallo schema attivo, dove le collisioni e gli identificatori lunghi sono già stati risolti.

4. Trova segnali confrontabili tra dataset

I parametri condivisi elencano concetti meteo comuni, unità di output e dataset che li supportano. Usa questo catalogo prima di confrontare modelli, poi risolvi la tupla esatta per ogni dataset invece di presumere che i nomi dei selettori coincidano.

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;

Valori, calcoli e filtri

Le colonne calcolate usano espressioni SQL familiari e possono fare riferimento agli alias definiti prima nell'elenco di selezione. Assegna prima un alias a una colonna meteo, poi riutilizzalo. Mantieni esplicite le conversioni di unità:

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);

Le condizioni sui valori meteo supportano BETWEEN, IN numerico, verifiche dei valori nulli, parentesi, NOT e combinazioni booleane. Unisci con AND le condizioni su tempo, posizione, lead time, membro ed esecuzione del modello; usa OR soltanto nelle condizioni sui valori meteo.

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;

Intervalli di tempo, tempo relativo e fusi orari

timeseries.forecasted_time è l'orario di validità. runs.forecasted_at è l'orario di inizializzazione del modello. Gli intervalli richiedono entrambi i limiti e includono i due estremi quando sono scritti con BETWEEN.

Per finestre adiacenti, preferisci un intervallo semiaperto come forecasted_time >= start AND forecasted_time < end. Evita di restituire due volte l'istante di confine quando si combinano query consecutive.

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;

Punti, griglie, lead time ed ensemble

Usa una coppia di coordinate per un punto, un elenco di tuple per più punti con nome oppure limiti di latitudine e longitudine con grid_step per una griglia regolare. La raccolta di query contiene esempi completi per ogni forma.

• Un punto: usa lat = value AND lon = value.
• Più punti: usa (lat, lon) o (lat, lon, name) con IN.
• Una griglia: limita entrambe le coordinate e imposta grid_step in gradi. Passi più piccoli selezionano più punti e consumano più quota.

Mantieni efficienti le query

L'utilizzo della quota dipende dai dati meteo letti per valutare una query, non dal numero di righe restituite. Una condizione su un valore meteo o su un alias calcolato, come temp_c > 30, può eliminare righe dal risultato soltanto dopo che i valori sono stati letti. Una query grande può quindi consumare molta quota anche se i filtri sui valori restituiscono pochissime righe.

Le condizioni su tempo di previsione, posizione, lead time e membro dell'ensemble riducono i dati selezionati. Le scelte seguenti hanno l'effetto maggiore:

• Usa timeseries a meno che ti serva espressamente la cronologia di più esecuzioni del modello.
• Mantieni brevi gli intervalli di tempo oppure usa un elenco di tempi esatti.
• Seleziona soltanto le colonne dei parametri meteorologici necessarie.
• Preferisci punti esatti a una griglia ampia; quando usi una griglia, scegli un grid_step adeguato.
• Limita il lead_time e seleziona soltanto i membri dell'ensemble necessari.

Usa l'ordinamento per l'esplorazione

ORDER BY è pensato soprattutto per sessioni interattive ed esplorazione dei dati, quando un risultato subito leggibile giustifica un lavoro aggiuntivo. Per una query limitata, ordinare prima per la colonna temporale principale consente in genere di restituire le righe progressivamente. Usa forecasted_time per timeseries o forecasted_at per runs, scegli una delle due direzioni e aggiungi, se necessario, colonne selezionate o alias come chiavi secondarie.

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;

Per runs, inizia con forecasted_at e limita entrambi gli estremi di lead_time. Se un risultato ordinato è troppo grande per essere elaborato in sicurezza, restringi la selezione oppure rimuovi ORDER BY e ordinalo nell'applicazione.

Per caricamenti storici e altri trasferimenti di dati ad alto volume, ometti ORDER BY. Se l'ordine è importante, ordina i dati dopo averli ricevuti. In questo modo l'ordinamento lato server non limita la velocità, soprattutto quando una selezione ampia è combinata con filtri sui valori meteo.

Usa LIMIT per la dimensione del risultato, non per la quota

LIMIT è utile per mantenere piccolo l'output interattivo, ma non definisce la quantità di dati meteo letti. Filtri e ordinamento possono leggere molti più dati di quelli contenuti nel risultato finale. Usa i controlli di selezione qui sopra quando devi ridurre l'utilizzo della quota.

Avanzato: convalida una query con EXPLAIN

La maggior parte delle query non richiede EXPLAIN. Anteponilo a una query meteo per convalidare l'istruzione e vedere informazioni diagnostiche senza recuperare righe meteo né consumare la quota delle query. È utile soprattutto per la risoluzione dei problemi e l'assistenza.

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;

Streaming, annullamento ed errori

Le righe diventano disponibili progressivamente. La loro visualizzazione immediata dipende dal client o dalla libreria MySQL: per query grandi usa l'interfaccia per risultati non bufferizzati, streaming, iterativi o a blocchi. L'impostazione esatta dipende dal client; l'appendice di riferimento dei client rimanda alla documentazione di ogni libreria.

• Disconnessione del client: la chiusura della connessione annulla la query attiva.
• CLI MySQL: premi Ctrl+C per interrompere la query attiva.

Risoluzione dei problemi

SHOW SESSION STATUS LIKE 'Compression%';

Usa la connessione come strumento autodescrittivo per gli agenti IA

Qualsiasi connettore generico per database MySQL, incluso uno esposto come strumento MCP, può collegarsi a mysql.gribstream.com:3307. Fornisci il token API tramite la configurazione segreta del connettore.

Fornisci all'agente il file di istruzioni qui sotto. Lo schema e le tabelle del catalogo gli consentono di scoprire dataset, colonne meteo, unità, mappature esatte dei selettori, regole del dialetto ed esempi pronti all'uso prima di costruire una query.

1. Leggi gribstream.sql_dialect e gribstream.query_examples.
2. Cerca in gribstream.datasets, poi esegui SHOW FULL COLUMNS per la tabella meteo scelta.
3. Usa gribstream.selector_columns quando serve la mappatura a un selettore JSON esatto o a GS_VALUE.
4. Costruisci ed esegui la query limitata più piccola che risponde alla domanda.
5. Usa EXPLAIN soltanto per convalidare o diagnosticare una query.

Scarica le istruzioni GribStream MySQL per agenti per il flusso di lavoro completo, i limiti della sintassi e le regole per recuperare i dati.

SQL supportato e limiti intenzionali

Questi limiti mantengono prevedibili le query, incrementali i risultati e chiari gli errori, invece di accettare SQL con comportamenti sorprendenti.

Appendice: riferimenti per la configurazione dei client

TLS, compressione, buffering dei risultati, annullamento, timeout e pooling delle connessioni vengono configurati dal client o dal driver, non tramite SQL. Consulta la documentazione della libreria che usi davvero per connetterti.