astroquery.gaiaで取得結果が2000件で止まる場合の対処法（sync/asyncの違い）

はじめに

Gaia DR3 カタログを Python の Astroquery からクエリして星を取得していたところ、
どのような条件でも取得結果が常に 2000 件で止まる という挙動に遭遇しました。

エラーは出ず、クエリも正しく見えるため最初は自分の書き方を疑いましたが、
調べていくと sync / async の使い分け が関係していそうだと分かりました。

本記事では、そのときの実際の検証ログを共有します。

検証例：SS 433 周辺を Gaia DR3 で取得

比較星選択の前処理として、SS 433 周辺の比較的狭い領域（±0.1° 程度）を Gaia DR3 で取得しました。

from astroquery.gaia import Gaia

query = """
SELECT ra, dec, phot_g_mean_mag
FROM gaiadr3.gaia_source
WHERE ra BETWEEN 287.86 AND 288.06
AND dec BETWEEN 4.88 AND 5.08
"""

同期クエリ（launch_job）

job = Gaia.launch_job(query)
result = job.get_results()

print(len(result))

出力例

2000

この領域は銀河面に近く、明らかに 2000 個を超える星が存在するはずですが、
結果は 毎回 2000 件で止まりました。

非同期クエリ（launch_job_async）

同じクエリを、非同期クエリで実行します。

job = Gaia.launch_job_async(query)
result = job.get_results()

print(len(result))

出力例

5901

同期クエリでは見えていなかった星が、
非同期クエリでは取得できている ことが確認できました。

sync / async の違いを整理する

astroquery.gaia には、クエリを投げる方法として次の 2 種類が用意されています。

• Gaia.launch_job()（同期クエリ）
• Gaia.launch_job_async()（非同期クエリ）

ここでいう「同期 / 非同期」は、クエリの実行方法と結果の受け取り方の違いを指しています。

• launch_job()（同期）
  → リクエストを投げ、その場で結果が返る前提の実行方式
  （短時間で終わる・結果が大きすぎないケース向き）

• launch_job_async()（非同期）
  → サーバ側でジョブとして実行し、完了後に結果を取得する方式
  （時間がかかる／結果が大きい可能性があるケースに向く）

参考：astroquery Gaia API
https://astroquery.readthedocs.io/en/latest/gaia/gaia.html

（なお、筆者が確認した限りでは、公式ドキュメント上に返却件数の上限や制限についての明示的な記述は見当たりませんでした。）

実務上で注意したいのは、

• エラーが出ない
• 件数が途中で打ち切られていても分からない

という点です。
そのため、結果をそのまま信じてしまうと、
「取得できているように見えて、実は欠けている」 状態に陥る可能性があります。

おわりに

今回は SS 433 周辺で気づきましたが、星密度の高い領域を扱う場合、誰でも遭遇し得る挙動だと思います。
実務上は、星数が多くなりそうな場合は launch_job_async() を使う方が安全だと思います。

同じところで詰まった方の参考になれば幸いです。