Consulte dados meteorológicos com as ferramentas que você já usa

Começar

Você só precisa de um token de API do GribStream e de um cliente ou biblioteca compatível com MySQL.

1. Crie um token de API gratuito ou use um token existente.
2. Use gribstream como nome de usuário e o token de API como senha.
3. Escolha um dataset, como gfs, como banco de dados e conecte-se.

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

O cliente MySQL de linha de comando solicita o token sem colocá-lo no histórico do shell. Neste comando, --quick faz o cliente imprimir as linhas à medida que chegam, em vez de esperar o resultado completo. Outros clientes usam configurações diferentes para resultados incrementais.

As consultas MySQL usam o mesmo token e a mesma cota das consultas da API HTTP. O uso se baseia nos dados meteorológicos lidos para responder à consulta. Se você não souber qual dataset usar, explore o catálogo de modelos; gfs é um bom ponto de partida global.

Por que MySQL?

Linguagens e ferramentas com um driver MySQL podem usar essa conexão familiar para consultar o GribStream. Você não precisa operar um servidor MySQL, importar arquivos meteorológicos nem aprender uma nova biblioteca.

A conexão é somente leitura e foi criada para dados meteorológicos. Os datasets aparecem como bancos de dados, os campos meteorológicos podem ser explorados e o SQL não compatível retorna um erro claro.

Encontre uma coluna meteorológica e consulte-a

Cada parâmetro meteorológico do GribStream aparece como uma coluna MySQL específica do dataset. Depois de escolher um dataset, consulte as colunas disponíveis antes de escrever a consulta:

SHOW FULL COLUMNS FROM gfs.timeseries;

No resultado, copie o valor de Field de que você precisa. Comment mostra o nome legível, as unidades nativas e o equivalente exato em GS_VALUE(...). Para a temperatura GFS a 2 m, a coluna é tmp_2_m_above_ground.

Estas três formas identificam o mesmo parâmetro meteorológico. A coluna é a forma SQL mais simples; GS_VALUE é a alternativa de seletor exato ao traduzir uma consulta existente da API HTTP ou escolher o seletor dinamicamente. A forma JSON é o seletor mostrado nas páginas dos modelos.

tmp_2_m_above_ground

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

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

Copie os nomes das colunas meteorológicas de SHOW FULL COLUMNS ou gribstream.selector_columns em vez de montá-los. A maioria é legível; nomes longos ou que colidem recebem um sufixo determinístico. Os seletores exatos diferenciam maiúsculas de minúsculas.

Esta consulta retorna as próximas seis horas de temperatura GFS a 2 m para um ponto:

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;

Esta coluna meteorológica publica valores em kelvin. Consulte seu Comment ou o catálogo para saber as unidades, em vez de deduzi-las pelo nome da coluna ou pelo alias.

O resultado é formado por linhas comuns. Os valores abaixo são ilustrativos:

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

Use o processo de pesquisa no catálogo para procurar colunas pelo nome do parâmetro, verificar as unidades e recuperar o seletor JSON exato ou a expressão GS_VALUE quando necessário.

Se a conexão já selecionou gfs, use FROM timeseries. Caso contrário, qualifique a tabela como gfs.timeseries.

Comece por uma consulta que funciona

Escolha o exemplo mais próximo do seu objetivo, abra-o e altere apenas o dataset, a coluna meteorológica encontrada, os horários ou os locais necessários. Copie os nomes de SHOW FULL COLUMNS em vez de tentar adivinhar como um seletor é normalizado.

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;

Conecte-se pela sua linguagem de programação

Escolha uma linguagem de programação abaixo. Cada exemplo estabelece uma conexão segura, executa a mesma pequena consulta meteorológica e lê as linhas. Guarde o token em uma variável de ambiente ou gerenciador de segredos; nunca o coloque em uma string de conexão versionada.

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

Para resultados grandes, use o iterador de linhas, modo streaming ou equivalente do seu driver para evitar que ele mantenha todo o resultado na memória.

Escolha timeseries ou runs

Cada dataset oferece as mesmas duas formas de tabela meteorológica. Escolha a tabela pela pergunta que quer responder, e não pelas colunas que deseja retornar.

forecasted_at é o horário de inicialização do modelo. forecasted_time é o horário válido previsto. lead_time é a diferença entre eles em horas; pode ser selecionado ou filtrado.

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;

Descubra datasets, colunas meteorológicas e seletores exatos

Não adivinhe nomes de colunas, níveis de parâmetros ou unidades. Encontre um dataset, consulte suas colunas meteorológicas e use o mapeamento do seletor exato apenas quando precisar da forma da API ou da alternativa GS_VALUE.

1. Encontre um 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. Explore as colunas meteorológicas

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

3. Pesquise os mapeamentos ou use um seletor exato

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 relaciona cada coluna meteorológica ao nome legível, às unidades, ao seletor JSON e à expressão GS_VALUE equivalente. A consulta exige uma condição exata em dataset.

Use o column_name gerado no SQL habitual. Use GS_VALUE(name, level, info) quando precisar de uma tradução direta de um seletor da API. Este seletor de gefsatmosmean tem um valor info não vazio, portanto exige os três argumentos:

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

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

As páginas dos modelos continuam mostrando o seletor JSON canônico e sua alternativa exata com GS_VALUE. Copie os nomes das colunas SQL do esquema em uso, onde colisões e identificadores longos já foram resolvidos.

4. Encontre sinais comparáveis entre datasets

Os parâmetros compartilhados listam conceitos meteorológicos comuns, unidades de saída e os datasets compatíveis. Consulte esse catálogo antes de comparar modelos e depois resolva a tupla exata de cada dataset, sem presumir que os seletores têm os mesmos nomes.

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;

Valores, cálculos e filtros

Colunas calculadas usam expressões SQL familiares e podem fazer referência a aliases definidos anteriormente na lista de seleção. Primeiro atribua um alias a uma coluna meteorológica e depois reutilize-o. Escreva as conversões de unidades de forma explícita:

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

Condições sobre valores meteorológicos aceitam BETWEEN, IN numérico, testes de NULL, parênteses, NOT e combinações booleanas. Una com AND as condições de horário, local, lead time, membro e execução do modelo; use OR apenas entre condições sobre valores meteorológicos.

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;

Intervalos, tempo relativo e fusos horários

timeseries.forecasted_time é o horário válido. runs.forecasted_at é o horário de inicialização do modelo. Intervalos exigem os dois limites e incluem ambas as extremidades quando escritos com BETWEEN.

Para janelas adjacentes, prefira um intervalo semiaberto, como forecasted_time >= start AND forecasted_time < end. Assim, o instante da fronteira não aparece duas vezes quando consultas consecutivas são combinadas.

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;

Pontos, grades, lead times e ensembles

Use um par de coordenadas para um ponto, uma lista de tuplas para vários pontos nomeados ou limites de latitude e longitude com grid_step para uma grade regular. Os exemplos de consultas incluem cada formato.

• Um ponto: use lat = value AND lon = value.
• Vários pontos: use (lat, lon) ou (lat, lon, name) com IN.
• Uma grade: limite as duas coordenadas e defina grid_step em graus. Passos menores selecionam mais pontos e consomem mais cota.

Mantenha as consultas eficientes

O uso da cota se baseia nos dados meteorológicos lidos para avaliar uma consulta, e não no número de linhas retornadas. Uma condição sobre um valor meteorológico ou alias calculado — como temp_c > 30 — só pode remover linhas depois que esses valores forem lidos. Portanto, uma consulta grande pode consumir muita cota mesmo que os filtros retornem poucas linhas.

Condições sobre horário de previsão, local, lead time e membro do ensemble reduzem os dados selecionados. Estas escolhas têm o maior efeito:

• Use timeseries, a menos que precise do histórico de várias execuções do modelo.
• Mantenha os intervalos curtos ou use uma lista de horários exatos.
• Selecione apenas as colunas de parâmetros meteorológicos necessárias.
• Prefira pontos exatos a uma grade ampla; ao usar uma grade, escolha um grid_step adequado.
• Limite lead_time e selecione somente os membros necessários do ensemble.

Use a ordenação para explorar

ORDER BY é destinado principalmente a sessões interativas e exploração de dados, quando vale a pena receber um resultado legível imediatamente. Em uma consulta limitada, começar a ordenação pela principal coluna de tempo geralmente permite receber linhas de forma incremental. Use forecasted_time para timeseries ou forecasted_at para runs, escolha qualquer direção e adicione colunas ou aliases selecionados como chaves secundárias quando necessário.

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;

Para runs, comece por forecasted_at e limite os dois lados de lead_time. Se um resultado ordenado for grande demais para processamento seguro, restrinja a seleção ou remova ORDER BY e ordene na aplicação.

Para cargas históricas e outras extrações de grande volume, omita ORDER BY. Se a ordem for importante, ordene os dados depois de recebê-los. Assim, a ordenação não limita a vazão, principalmente quando uma seleção ampla é combinada com filtros de valores meteorológicos.

Use LIMIT para o tamanho do resultado, não para a cota

LIMIT ajuda a manter pequena uma saída interativa, mas não define a quantidade de dados meteorológicos lidos. Filtros e ordenação podem ler muito mais dados do que o resultado final contém. Use os controles de seleção acima quando precisar reduzir o uso da cota.

Avançado: valide uma consulta com EXPLAIN

A maioria das consultas não precisa de EXPLAIN. Coloque-o antes de uma consulta meteorológica para validar a instrução e ver informações de diagnóstico sem buscar linhas nem consumir cota. Ele é útil principalmente para solução de problemas e suporte.

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;

Resultado incremental, cancelamento e erros

As linhas ficam disponíveis de forma incremental. A exibição imediata depende do cliente ou biblioteca MySQL, portanto use sua interface sem buffer, streaming, iterativa ou em blocos para consultas grandes. A configuração varia por cliente; o apêndice de clientes contém links para a documentação de cada biblioteca.

• Desconexão do cliente: fechar a conexão cancela a consulta ativa.
• Cliente MySQL: pressione Ctrl+C para interromper a consulta ativa.

Solução de problemas

SHOW SESSION STATUS LIKE 'Compression%';

Use a conexão como ferramenta autodescritiva para agentes de IA

Qualquer conector genérico de banco de dados MySQL — inclusive um exposto como ferramenta MCP — pode se conectar a mysql.gribstream.com:3307. Forneça o token de API pela configuração secreta do conector.

Forneça ao agente o arquivo de instruções abaixo. O esquema e as tabelas do catálogo permitem descobrir datasets, colunas meteorológicas, unidades, mapeamentos exatos de seletores, regras do dialeto e exemplos prontos antes de criar uma consulta.

1. Ler gribstream.sql_dialect e gribstream.query_examples.
2. Pesquisar em gribstream.datasets e depois consultar SHOW FULL COLUMNS para a tabela meteorológica escolhida.
3. Usar gribstream.selector_columns quando for necessário mapear um seletor JSON exato ou GS_VALUE.
4. Criar e executar a menor consulta limitada que responda à pergunta.
5. Usar EXPLAIN apenas para validar ou investigar uma consulta.

Baixe as instruções do GribStream MySQL para agentes, com o processo completo, os limites de sintaxe e as regras para obtenção dos dados.

SQL compatível e limites deliberados

Esses limites mantêm as consultas previsíveis, permitem resultados incrementais e geram erros claros, em vez de aceitar SQL com comportamento surpreendente.

Apêndice: referências de configuração dos clientes

TLS, compressão, buffer de resultados, cancelamento, limites de tempo e pools de conexão são configurados no cliente ou driver, não pelo SQL. Consulte a documentação da biblioteca que você utiliza.