レンコン畑でつかまえて

はじめてのDatabricks on AWS

2026-05-05T00:00:00Z

はじめに

上司から「Databricksを使えるようにしておいて」と言われることは長い人生のなかでは一度くらいはあるかもしれません。

「まぁ、公式リファレンスを見れば何とかなるやろ」と意気揚々と見に行くも、そもそもどこから読み始めたらよいかよくわからないリファレンスを前に心をへし折られた方もいると思います。私です

ここでは、私が実際にDatabricksをAWSに展開したときに知っておきたかった前提知識や参考になったページ、約1年程度運用して最初から考慮した方がよかったと思うプラクティスなどを紹介します。

前提知識

AWS

Databricksは基本的には顧客（つまり私たち）のAWS環境にデータを保存したり計算資源を作成します。 Serverless workspaceのようなものもあったりしますが、すべてをServerless workspaceで賄うのはたぶん無理だと思うのでいったん忘れてください。

Databricksでは主に以下のAWSリソースを使用するため、最低限概要をつかんでおく必要があります。

ストレージ（S3）

Databricksではあらゆる顧客データをS3のバケットに作成します。

生データはそのままオブジェクトとして保存されますし、テーブルデータはDelta Lakeと呼ばれるOpen Table Format（OTF）として保存されます。ワークスペースで作成したノートブックなども実体はS3に保存されます。

OTFにはそのほかにもApache Icebergなどがありますが、この段階では気にする必要はありませんし、そのうち違いは無くなるので将来的にはそんなこともありましたよねという感じになると思います。

また、使うのはS3 Tablesのようなものではなく普通のS3です。 Delta Lake自体にバージョニング機能（タイムトラベルクエリ）も持っているため、バケット側のバージョニングも使いません。

計算資源（EC2）

Databricksには主にクラシックコンピュートとサーバレスコンピュートの二種類があります。

そのうち、クラシックコンピュートは顧客のAWSアカウントで動作するEC2を実体としています。 EC2を稼働させるVPCがオンプレミスやほかのAWSリソースに接続しに行ける構成となっていれば、そのままDatabricksからオンプレミスのデータベースに接続することができます。

サーバレスコンピュートはDatabricks社のAWSアカウント上のKubernetesクラスタ上で動作しているらしいです。そのため、サーバレスコンピュート用の計算資源は管理する必要はありません。

ネットワーク（VPC・Peering・Direct Connect・Site-to-Site VPN）

クラッシックコンピュートの実体がEC2であるならば、そのEC2を稼働させるためのVPCも必要になります。

Databricksからオンプレミスのデータベースに接続する必要があれば、Direct ConnectやSite-to-Site VPNを使用してオンプレミスとの接続性を確保する必要があります。同様に、他のVPCのリソースに接続しに行く必要があればVPC Peeringなどで接続性を確保する必要があります。

この辺はDatabricks固有のお話というよりかは一般的なVPCネットワークの設計のお話となります。

Databricksコントロールプレーンへの権限の委譲（IAM）

AWSのリソースは顧客のAWSアカウントに作成しますが、クラシックコンピュート起動するたびに手動でEC2インスタンスを作成するわけではありません。

クロスアカウントアクセスが可能なIAMロールをDatabricksに連携しておいて、Databricksの制御側（この制御側をよくコントロールプレーンと呼びます）から必要なEC2インスタンスを作成したり削除してもらいます。

また、S3バケットに格納されているデータにアクセスするためのIAMロールなども作成して連携する必要があります。クラシックコンピュートやサーバレスコンピュートはこのIAMロールをAssume Roleしてデータに触りに行きます。

Databricks

Databricksではトップレベルの要素として、Unity Catalogとワークスペースが存在します。 Databricksの論理設計ではUnity Catalogとワークスペースの設計を最初に行います。

Unity Catalogの階層構造の設計や、ワークスペースの分割設計が今後のDatabricks運用に多大な影響を与えます。そのため、この部分の設計はふわっとやらない方が良いと思います。

Unity Catalog

Unity Catalog（UC）はデータを格納しアクセス権を管理するための入れ物となります。

UCはAWSの場合、リージョン毎に1つしか作成することができません。

UCでは常にcatalog.schema.objectという3タプルの識別子でオブジェクト（テーブル・ボリューム・モデル）を識別します。2つにしたり4つにしたりは出来ません。そのため、カタログやスキーマの階層構造の設計はその後のデータ整理に多大な影響を及ぼします。また、運用途中での変更には多大な労力がかかります。

What is Unity Catalog?

ワークスペース

UCがデータの入れ物であるならば、ワークスペースはプログラム（ノートブック・Job・パイプライン・ダッシュボード）と計算資源（クラスタ・Vecto Search）の入れ物となります。

ワークスペースは一つのリージョンの中に複数することができます。ワークスペースはアクセスの境界にもなるので、組織間のアクセス制御にワークスペースを使うことも多いです。

クラシックコンピュートとサーバレスコンピュート

クラシックコンピュートとサーバレスコンピュートはワークスペース作成時にどちらを使うか選択するようなものではなく、用途によってそれぞれ使い分けを行います。

サーバレスは制約は多いですが、起動がめっちゃ早いという1点だけでもかなり便利なので、個人的にはサーバレスでは出来ないこと以外は基本的にはサーバレスを使っています。

クラシックコンピュート
- メリット
  - VPCの構成によってはオンプレミスのリソースに接続しに行ける
  - EC2のインスタンスタイプやクラスタサイズを柔軟に構成できる
- デメリット
  - 起動に時間が掛かる
サーバレスコンピュート
- メリット
  - 起動がほぼ一瞬
- デメリット
  - サイズはいくつかのサイズから選ぶだけで、細かい調整は出来ない
  - （PrivteLinkの設定をしないと）オンプレミスのリソースには接続しに行けないうえに、PrivateLinkは追加のコストが掛かる
  - GPUは使えない

インフラ設計

ワークスペースとAWSリソースの関係

ワークスペースにはEC2を動かすためのアベイラビリティゾーンが異なるサブネットが最低2つと、ワークスペースのリソースを保存するためのS3バケットが1つ必要になります。

ワークスペースを作成するのに指定したバケットはそのままExternal locationsとしても登録されるので、UCを経由してテーブルなどのUCオブジェクトを保存するのにも使用できます。

また、ワークスペースのバケット以外にも別途バケットを作成してExternal locationとして登録すれば、UCオブジェクトを登録する専用のバケットとして使用することもできます。

VPC構成

EC2を動かすためのサブネットは最低限インターネットへの接続性があれば大丈夫です。また、S3用のゲートウェイエンドポイントには費用が掛からないのと、用意しないとS3のアウトバンドコストがまぁまぁ大変なことになるので最低限S3ゲートウェイエンドポイントは用意しておきます。

あとは、オンプレミスのデータベースやほかのVPCへの接続性のためにDirect ConnectやVPC Peeringを必要に応じて設定します。

ただし、この構成はクラシックコンピュートとコントロールプレーンの通信はインターネットを経由します。業界のコンプライアンス要件などでインターネットを経由できない場合、AWSサービスエンドポイントとDatabricksバックエンドサービスへのPrivateLinkを追加で構成することでインターネットへの接続性なしでクラシックコンピュートを運用できます。

クラシックコンピュートがインターネットへの接続性を持たない構成にすることもできます。この場合、ノートブックでPythonライブラリをインターネット経由でインストールすることが出来なくなるので、別途プロキシリポジトリを建てるかwheelパッケージをあらかじめダウンロードしてS3などに配置する必要があります。

厳密なインターネット分離が求められる場合、クラシックコンピュート⇔コントロールプレーン間だけでなくユーザ⇔コントロールプレーン間でもインターネットを経由しないことが求められるかと思います。その場合、フロントエンドへの接続もインターネットを経由しない構成にすることができます。

この辺を真面目にやろうとすると結構大変なので、やる場合は実力のあるサポートベンダに相談した方が良いです。

プラクティス

VPCは新規で作成するか？既存のを流用するか？

導入企業の既存のAWS環境の設計やポリシーに強く依存しますが、基本的には分けた方が良いと思います。 VPCが分かれてもVPC PeeringでほかのVPCに触りに行くことが出来ますし、Databricks向けのリソースと他のリソースが混ざる心配もありません。

もっというと、アカウントを分けるぐらいの勢いで行っても良いと思います。

サブネットサイズ設計

クラシックコンピュートのインスタンスは対コントロールプレーンに1つと、クラスタ内の通信に1つの計2つのプライベートアドレスを使用します。また、クラスタの再起動時や拡張・縮退時など稼働しているインスタンスよりも多い数のプライベートアドレスを使用することがあります。

とはいえ、あるワークスペースに割り当てられたサブネットは他のワークスペースに重複して割り当てが出来ないため、過剰に大きいサブネットに分割してしまうとサブネットが足りなくなる場面も出てきます。私です

個人的には最小のサブネットを/22として、稼働予定のインスタンスの倍の数を収容できるサブネットに分割するのがいいのかなと思っています。

マルチAZ構成

ワークスペースに関連付けるサブネットは最低でも2つ以上のAZで構成しなければいけませんが、高可用構成にするには最低でもNAT Gatewayも1つのAZに1つ作成するなど全体として単一障害点をなくさないといけません。

運用としてはクラシックコンピュートがワークロードの主体になっており、高可用性が求められるのであれば単一障害点をなくす設計を行わないといけません。

対して、普段のワークロードはサーバレスコンピュートが主体でクラシックコンピュートはオンプレミスに触りに行くだけとかであれば費用対効果の観点から高可用を捨ててしまってもいいかもしれません。

リソースの命名規則

DatabricksとAWSという異なる世界のリソースを一緒に扱うため、リソースの命名の一貫性には気を付けています。過去の経緯から一貫性を欠いているものも一部ありますが、こんな感じで短さよりも分かりやすさを優先して命名をしています。

Databricks

ワークスペース
- {リージョン名}-{連番}
- apn1-0

AWS

VPC
- databricks-vpc-{リージョン}
- databricks-vpc-apn1
サブネット
- databricks-subnet-{ワークスペース}-{AZ}
- databricks-subnet-apn1-0-a
バケット（カタログ）
- databricks-catalog-{リージョン}-rootbucket
- databricks-catalog-apn1-rootbucket
バケット（ワークスペース）
- databricks-workspace-{ワークスペース名}-rootbucket
- databricks-workspace-apn1-0-rootbucket

Terraformでのリソースのデプロイ

どこまでをTerraformなどのIaCに乗せるかは組織や担当者のIaCへの理解度に依存すると思います。

私はAWSのリソースはTerraformでデプロイしていますが、Databricksのリソースは手動で展開しています。

Databricksのリソースはものによっては一度作成したら削除出来ない・一度設定したら削除して再作成しないと変更できないリソースがそこそこあり、無理にTerraform化してよく分からないことになるくらいだったら手動で管理した方が管理しやすいと考えてそのようにしています。

カタログ設計

UCではcatalog.schema.objectの3タプルでオブジェクトが識別されます。また、アクセス権は階層構造で設定するので、3タプルの構造がそのままアクセス権の構造に影響します。

この辺は組織のポリシーやデータの特性に大きく影響を受けるためこれが正解というのはありませんが、一例として以下のようなイメージが考えられます。

ここではメダリオンアーキテクチャに従って、販売_bronzeをブロンズ層としてデータの着地点として利用します。

後続のシルバー層に向けてデータを供給する役目を持つことからブロンズ層はユーザには見せません。ブロンズ層は可能な限り上流のシステムに近い構成とし、認知負荷を下げます。

シルバー層ではすべてのユーザが見れる情報と閲覧できる人が限られる情報で分けてカタログに収納します。閲覧できる人が限られる情報についてはカタログとスキーマで権限を制御します。

catalog	schema	table
販売_bronze	販売	受注
		売上
		商品情報
	CRM	顧客情報
販売	販売	受注
		売上
		商品情報（原価情報なし）
	CRM	顧客情報（個人情報なし）
販売_センシティブ	原価	商品情報（原価情報あり）
販売_センシティブ	CRM	顧客情報（個人情報あり）

ワークスペース設計

1年近く運用してみて、ワークスペースは以下のように分割するのがいいのかなという感覚を持っています。まぁ、あくまでも私が所属している組織で都合が良いというだけで、あらゆる組織に適用できるかというと微妙ですが・・・

構成としては、ユーザが触る用のワークスペースとデータエンジニアが作業を行うデータの取り込み・パイプライン実行用のワークスペースを最低限分離します。

これはデータ取り込み用のリソース（ジョブ・パイプライン）と利用者が普段触るリソース（ダッシュボード・Genieスペース）を分離する意図があります。もちろん、アクセス権を設定すれば触れなくはなりますが、ワークスペースへのアクセス権レベルで制御してしまえば細かいリソース毎のアクセス権は気にしなくてもよくなります。

また、同時に複数のワークスペースからS3上のDeltaテーブルを変更するとデータが壊れるので、データを変更する操作はなるべく単一のワークスペースに寄せるようにしています。

また、ある程度の大きさの組織毎にワークスペースを分離します。ここでの組織とは、組織図に厳密に対応するものではなく、組織の属性に応じたものを考えています。組織の属性に応じて、どのカタログをアタッチするかの管理を行い、まずはアタッチするカタログレベルでデータへのアクセス権を絞ります。

もちろん、その先の細かいアクセス権の制御はUnity CatalogなりABACなりで制御を行います。

同様にDatabricks Appsやダッシュボード・Genieスペースはワークスペースに紐づくため、生産部門が営業部門のアプリに触らないまたはその逆が起こらないという観点からもワークスペースを分離します。

あとは、たまにやべー挙動をする利用者が出てくると思うので、その監査用にsystem.auditスキーマのテーブルを使ってアクティビティ監査を行う専用のワークスペースを置いておきます。

カタログ専用バケットのデプロイ

私の組織ではワークスペースとデータを完全に分離したいという考え方からカタログの保存先としてワークスペースのバケットは使用せず、カタログ保存用のバケットを用意したうえでそこに保存しています。

こうしておけばどのカタログがどのバケットに入っているかなどは気にしなくて良くなるので、組織のニーズに応じて柔軟にワークスペースの作成と削除を行えます。

ただし、複数のワークスペースから同じテーブルに変更をかけるとデータが壊れるので、テーブルの更新を行うワークスペースには気を付けた方が良いです。

新機能の検証用にアメリカリージョンにもワークスペースが欲しいよね

Databricksは過去からの傾向として、新機能のPreviewはアメリカのリージョンから利用可能になることが多いです。

私の組織ではアメリカの主要リージョンの中で日本からのレイテンシが比較的小さいus-west-2（オレゴン）に機能の評価用ワークスペースを構築しています。

その他参考リファレンス

VPC

Configure a customer-managed VPC

Storage

Workspace

Create a workspace with manual AWS configurations

おわり

DatabricksのSpark Declarative Pipelinesを使って簡易的な家計簿を作りたい

2026-04-29T00:00:00Z

はじめに

DatabricksにはAI Functionsがあり、ノートブックやSQL Editorなどで使用できます。

いつからかSpark Declarative Pipelinesでも使えるようになっており、パイプラインだけでOCRと抽出が完結できるようになっていました。

そこで、今回はボリュームに格納されたレシートから日時と金額を抽出してダッシュボードに表示するまでの処理をSpark Declarative Pipelinesで実装して、Declarative Automation Bundlesでデプロイできるようにしてみました。

jyuch/public-expenses

パイプラインの実装

以下の流れのパイプラインを実装します。

Volumeからレシートのイメージをロード
ai_parse_documentでOCR処理を実行
ai_queryで抽出結果を構造化
構造化データをフラット化してシルバーテーブルに変換

基本的にai_〇〇は実行にまぁまぁの時間が掛かるので、毎回全部のイメージの再処理をしていたら実行時間がとんでもないことになります。そのため、ストリーミングテーブルを使用して差分実行を行うようにします。

この辺もCREATE STREAMING TABLEとSTREAM()でチェックポイントの管理をしなくても良きにしてくれるのでSDPは大好きです。

まずはVolumeに格納されているレシートのイメージをロードします。

CREATE STREAMING TABLE raw_receipts AS
SELECT
  path,
  modificationTime,
  length,
  content
FROM
  STREAM(READ_FILES('/Volumes/expenses/default/receipt_images/', format => 'binaryFile'));

そうしたら、ai_parse_documentでOCRを実行します。

CREATE STREAMING TABLE parsed_receipts AS
SELECT
  path,
  modificationTime,
  length,
  content,
  ai_parse_document(content, Map('version', '2.0')) AS parsed_receipt
FROM
  STREAM(raw_receipts);

ai_queryのresponseFormatにJSON Schemaを指定して構造化出力を行わせます。本当はSTRUCT<>で構造体の定義を指定できるはずなのですが、「Spark Declarative Pipelinesのバグにエンカウントしたのでバグ報告ヨロ」みたいなエラーが表示されるので、あきらめてJSON Schemaを指定しています。

個人的にはJSON Schemaは書式が冗長なので、できればSTRUCT<>の方の構文を使いたいです。

CREATE STREAMING TABLE structured_receipts AS
SELECT
  path,
  ai_query(
    'databricks-qwen3-next-80b-a3b-instruct',
    CONCAT(
      'レシートをパースした結果が与えられます。そこから購入日と合計金額を抽出しなさい。',
      parsed_receipt
    ),
    responseFormat =>
      '{
        "type": "json_schema",
        "json_schema": {
          "name": "structured_food_receipts",
          "schema": {
            "type": "object",
            "properties": {
              "purchase_date": {
                "type": "string",
                "format": "date"
              },
              "total_amount": {
                "type": "integer"
              }
            },
            "required": [
              "purchase_date",
              "total_amount"
            ]
          },
          "strict": true
        }
      }'
  ) AS structured_receipt
FROM
  STREAM(parsed_receipts);

抽出したパスからレシートの種類（食費とか日用品とか）を付与しています。また、JSON形式の文字列からSTRUCT<>に変換します。

購入日とかを抽出するタイミングでカテゴライズをしてもいいのですが、精度が出なかったのでひとまずファイルパスで識別させています。

CREATE STREAMING TABLE flatten_receipts AS
SELECT
  path,
  regexp_extract(path, '/([^/]+)/[^/]+$', 1) AS kind,
  try_cast(
    try_parse_json(structured_receipt) AS STRUCT<purchase_date DATE, total_amount INT>
  ) AS receipt
FROM
  STREAM(structured_receipts);

最後にフラット化すればひとまずは家計簿テーブルが完成します。名前とやっていることが微妙に一致してませんが、まぁ、その・・・。

CREATE OR REPLACE MATERIALIZED VIEW receipts AS
SELECT
  path,
  kind,
  receipt.purchase_date,
  receipt.total_amount
FROM
  flatten_receipts;

DABでの展開

パイプラインを手動でデプロイしてもいいのですが、全部自動でできた方がうれしいですよね。

ということでDABで一発デプロイできるようにします。

特にひねりのないdatabricks.ymlとresources/expenses.pipeline.ymlを定義します。

bundle:
  name: expenses
  uuid: 00000000-0000-0000-0000-000000000000

include:
  - resources/*.yml

variables:
  catalog:
    description: The catalog to use
  schema:
    description: The schema to use
  ingest_from:
    description: The path log ingestion

targets:
  dev:
    mode: development
    default: true
    variables:
      catalog: expenses
      schema: dev
  prod:
    mode: production
    workspace:
      root_path: /Workspace/Bundles/${bundle.name}/${bundle.target}
    variables:
      catalog: expenses
      schema: prod

resources:
  pipelines:
    expenses:
      name: expenses
      catalog: ${var.catalog}
      schema: ${var.schema}
      serverless: true
      root_path: "../src/expenses"

      libraries:
        - glob:
            include: ../src/expenses/transformations/**

      environment:
        dependencies:
          - --editable ${workspace.file_path}

あとは🚀ボタンで一発デプロイです。

ダッシュボードの作成

あとはお好みの種類のグラフでダッシュボードを作るだけです。

ダッシュボードもDABでデプロイ出来ます。お仕事ではダッシュボードもパイプラインと同じようにDABでデプロイしているのですが、小回りが利かなくなるので趣味ならこの辺はお好みでいいと思います。

おわりに

SQLだけでレシートのOCR ⇒ 情報の抽出が完結しました。また、差分更新も勝手にやってくれます。

宣言的に実装からデプロイまでできるので管理しやすいです。皆様のお仕事のお供のぜひぜひ

おわり

Databricks Zerobus Ingestでサーバレスでリアルタイムにデータを流し込みたかった

2026-04-04T00:00:00Z

はじめに

ついにDatabricksのZerobus IngestがGAとなりました。

Preview版ではデフォルトストレージは対応していないとありましたが、GAになったタイミングでその表示が消えたので、Databricks Free Editionで試してみることにしました。

テーブルの作成

Databricks上のテーブルからProtobufの定義を生成出来るようなので、まずはテーブルを作成します。

ここではひとまず私が必要そうなデータ型に絞ってテーブルを作成します。

CREATE OR REPLACE TABLE workspace.default.zerobus_sample (
    id INT,
    name STRING,
    create_at TIMESTAMP
);

Protobufの定義生成

テーブルを作成したら、テーブル定義からProtbufの定義を生成します。

Zerobus Ingest SDKに生成するためのツール（generate_files）があるので、それを使って生成します。

ツールはサービスプリンシパル経由で触りに行くタイプなので、サービスプリンシパルを作成してシークレットを生成しておきます。

また、テーブル定義も触りに行く必要があるので、サービスプリンシパルに権限を振るのを忘れないようにして下さい。（1敗）

ツールはRustを使って実装されているので、Rustの処理系をあらかじめインストールしておきます。あとは以下のコマンドで生成できます。

cargo run -- \
  --uc-endpoint "<your_uc_endpoint>" \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --table "workspace.default.zerobus_sample"

クライアントの実装

今回はRustで書いていきます。

必要なライブラリは以下の通りなのですが、databricks-zerobus-ingest-sdkのprost系は0.13に依存しているので、prostだけは0.13を明示的に指定してインストールする必要があります。（1敗）

[dependencies]
# 必須
databricks-zerobus-ingest-sdk = "1.0.1"
prost = "0.13.5"
prost-types = "0.13.5"
tokio = { version = "1", features = ["full"] }
# お好みで
anyhow = "1"
chrono = "0.4"

あとは公式のサンプルをベースに簡単な書き込み処理を実装していきます。

use crate::samples::TableZerobusSample;
use databricks_zerobus_ingest_sdk::{
    ProtoMessage, StreamConfigurationOptions, TableProperties, ZerobusSdk, ZerobusStream,
};
use prost::Message;
use prost_types::{DescriptorProto, FileDescriptorSet};
use std::fs;

pub mod samples {
    include!("../output/zerobus_sample.rs");
}

const SERVER_ENDPOINT: &str = "<workspace id>.zerobus.<region>.cloud.databricks.com";
const DATABRICKS_WORKSPACE_URL: &str = "https://dbc-12345678-90ab.cloud.databricks.com";
const DATABRICKS_CLIENT_ID: &str = "00000000-0000-0000-0000-000000000000";
const DATABRICKS_CLIENT_SECRET: &str = "dose12345678901234567890123456789012";

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let descriptor_proto = load_descriptor(
        "output/zerobus_sample.descriptor",
        "zerobus_sample.proto",
        "table_zerobus_sample",
    );

    let table_properties = TableProperties {
        table_name: "workspace.default.zerobus_sample".to_string(),
        descriptor_proto: Some(descriptor_proto),
    };

    let stream_configuration_options = StreamConfigurationOptions {
        max_inflight_requests: 100,
        // RecordType::Proto is the default.
        ..Default::default()
    };

    let sdk_handle = ZerobusSdk::builder()
        .endpoint(SERVER_ENDPOINT)
        .unity_catalog_url(DATABRICKS_WORKSPACE_URL)
        .build()?;

    let mut stream = sdk_handle
        .create_stream(
            table_properties.clone(),
            DATABRICKS_CLIENT_ID.to_string(),
            DATABRICKS_CLIENT_SECRET.to_string(),
            Some(stream_configuration_options),
        )
        .await?;

    ingest_with_offset_api(&mut stream).await?;

    stream.close().await?;
    println!("Stream closed successfully");
    Ok(())
}

/// Recommended API: returns offset directly after queuing.
async fn ingest_with_offset_api(stream: &mut ZerobusStream) -> anyhow::Result<()> {
    println!("=== Offset-based API (Recommended) ===");

    let now = chrono::Utc::now().timestamp();

    // 1. Auto-encoding: ProtoMessage - pass message directly, SDK handles encoding.
    let order = TableZerobusSample {
        id: Some(1),
        name: Some("test".to_string()),
        create_at: Some(now),
    };

    let offset_id = stream.ingest_record_offset(ProtoMessage(order)).await?;
    println!("[Auto-encoding] Record sent with offset ID: {}", offset_id);
    stream.wait_for_offset(offset_id).await?;
    println!(
        "[Auto-encoding] Record acknowledged with offset ID: {}",
        offset_id
    );

    Ok(())
}

// Load descriptor from generated files
fn load_descriptor(path: &str, file: &str, msg: &str) -> DescriptorProto {
    let bytes = fs::read(path).expect("Failed to read descriptor");
    let file_set = FileDescriptorSet::decode(bytes.as_ref()).unwrap();

    let file_desc = file_set
        .file
        .into_iter()
        .find(|f| f.name.as_deref() == Some(file))
        .unwrap();

    file_desc
        .message_type
        .into_iter()
        .find(|m| m.name.as_deref() == Some(msg))
        .unwrap()
}

実装できたら早速実行してみましょう。

Unsupported table kind. Tables created in default storage are not supported. Error Code: 4024, Error State: 0.

無慈悲

おわりに

Zerobus Ingest connector limitations - Workspace and Target table

書いてある場所が移動しただけで、使えないんすね。

Free EditionでもS3を外部ロケーションとして登録してカタログをそっちに作成すれば使えるとは思いますが・・・

おわり

Hugging FaceのSentence TransformersモデルをUnity Catalogに登録してServing endpointsにデプロイしたい

2026-02-25T00:00:00Z

はじめに

大体タイトル通りです。

Databricksに最初から登録されている埋め込みモデルは英語のみで日本語に対応していないので、Serving endpointにデプロイするためにHugging Faceから好きなモデルを引っ張ってきてUnity Catalogに登録する方法を確認してみました。

ちなみにモデルを登録するだけなら以下のノートブックを使えば一発で登録できると思います。

🤗HFのモデルをUCに登録する君

環境のセットアップ

ノートブックにServerlessコンピュートをアタッチして、以下のライブラリをインストールします。

MLflowのSentence Transformersを使用したいため、mlflow[sentence-transformers]を指定してインストールします。

mlflow[sentence-transformers]==3.9.0
sentence-transformers==5.2.3

今回はConfigurationのDependenciesから追加しましたが、たぶん%pipコマンドを使ってインストールしてdbutils.library.restartPython()しても良いと思います。

モデル名の入力とかスキーマの作成とか

このノートブックでは登録先のカタログ名とHugging Faceのモデル名をWidgetから受け付けます。

dbutils.widgets.text("uc_catalog_name", "", "UC Catalog name")
dbutils.widgets.text("hf_model_name", "", "Hugging Face Model name")

登録先のスキーマ名とモデル名は入力されたHugging Faceモデルから組み立てています。

UC_CATALOG_NAME = dbutils.widgets.get("uc_catalog_name")
HF_MODEL_NAME = dbutils.widgets.get("hf_model_name")
UC_SCHEMA_NAME = HF_MODEL_NAME.split("/")[0].replace("-", "_").replace(".", "_")
UC_MODEL_NAME = HF_MODEL_NAME.split("/")[1].replace("-", "_").replace(".", "_")

そうしたら登録先のスキーマを作成しておきます。

spark.sql(f"CREATE SCHEMA IF NOT EXISTS {UC_CATALOG_NAME}.{UC_SCHEMA_NAME}")

MLflowへのモデルのロギング

Sentence Transformers経由でHugging Faceのモデルを取得し、MLflowのSentence Transformersフレーバーを使用してモデルをロギングします。

import mlflow
from sentence_transformers import SentenceTransformer

mlflow.set_registry_uri("databricks-uc")

model = SentenceTransformer(HF_MODEL_NAME)

input_example = [
    "RFC 1034とRFC 1035は、Domain Name System（DNS）の基礎を定義する最も重要な仕様である。",
    "Paul Mockapetrisによって1987年に策定され、インターネットにおける名前解決の仕組み全体を規定している。",
]

with mlflow.start_run():
    model_info = mlflow.sentence_transformers.log_model(
        model=model,
        name=UC_MODEL_NAME,
        input_example=input_example,
    )

ロギングされたモデルにはモデルの実行に必要なライブラリが含まれるのですが、たまに必要な依存関係が足りずにServing endpointsへのデプロイに失敗することがあるので、事前に一度モデルが動作することを確認します。

大体10分位掛かるので、気長に待ちましょう。

mlflow.models.predict(
    model_uri=model_info.model_uri,
    input_data=input_example,
)

Unity Catalogへの登録

モデルが正常に動作することが確認出来たらUnity Catalogへ登録して完了です。

mlflow.register_model(
    model_info.model_uri, f"{UC_CATALOG_NAME}.{UC_SCHEMA_NAME}.{UC_MODEL_NAME}"
)

おわり

Databricksのread_files関数でもExcelファイルを読み込みたい

2026-01-17T00:00:00Z

2月8日追記

現時点ではフリガナ問題は解決しています。

また、より大きいファイルでも取り込めるようになっていました。ですが、調子に乗って大きなサイズを放り込むと処理が終わらないので、その辺はいい感じにする必要があります。

注意事項

本検証は2026年1月17時点の内容で検証しています。リリース版は挙動が異なる場合があります。

また、Databricks Free Editionで評価しています。そのため、商用版と挙動が異なる場合があります。

はじめに

Databricksのread_files関数はCSVやJSONフォーマットをいい感じに読み込んでくれる関数です。そのread_files関数がExcelファイルの読み込みをサポートしました。

ですが、Excelフォーマットをプログラムで扱う際のトラップに悩まされてきた生産性アプリケーション開発者も多いのではないでしょうか。

そこで、今回はトラップになりそうな部分の評価を行ってみました。

Office Open XMLフォーマット

今回はExcelフォーマットのうち、Office Open XMLフォーマット（xlsx）を評価してみます。そのOOXMLフォーマットのうち、今回の検証で触れる内容について軽く解説をしていきます。

OOXMLはXMLの名前がついている通り、主にzipで圧縮されたXMLファイルで構成されています。

たとえば、以下のようなExcelファイルをzip展開すると、以下のような構造となっています。

example.xlsx
│
│  [Content_Types].xml
│
├─docProps
│      app.xml
│      core.xml
│
├─xl
│  │  sharedStrings.xml
│  │  styles.xml
│  │  workbook.xml
│  │
│  ├─printerSettings
│  │      printerSettings1.bin
│  │
│  ├─theme
│  │      theme1.xml
│  │
│  ├─worksheets
│  │  │  sheet1.xml
│  │  │
│  │  └─_rels
│  │          sheet1.xml.rels
│  │
│  └─_rels
│          workbook.xml.rels
│
└─_rels
        .rels

そのうち、内容を確認する際に見るのが以下の二つのファイルになります。

`xl\worksheets\sheet1.xml`

xl\worksheets以下にはシート毎にシートの内容が含まれているXMLファイルが格納されています。

上記の例だと、こんな感じに内容になるはずです。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
    xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="x14ac xr xr2 xr3"
    xmlns:x14ac="http://schemas.microsoft.com/office/spreadsheetml/2009/9/ac"
    xmlns:xr="http://schemas.microsoft.com/office/spreadsheetml/2014/revision"
    xmlns:xr2="http://schemas.microsoft.com/office/spreadsheetml/2015/revision2"
    xmlns:xr3="http://schemas.microsoft.com/office/spreadsheetml/2016/revision3"
    xr:uid="{00000000-0001-0000-0000-000000000000}">
    <dimension ref="A1:B2" />
    <sheetViews>
        <sheetView tabSelected="1" workbookViewId="0" />
    </sheetViews>
    <sheetFormatPr defaultRowHeight="18.75" />
    <sheetData>
        <row r="1" spans="1:2">
            <c r="A1" t="s">
                <v>0</v>
            </c>
        </row>
        <row r="2" spans="1:2">
            <c r="B2" t="s">
                <v>1</v>
            </c>
        </row>
    </sheetData>
    <phoneticPr fontId="1" />
    <pageMargins left="0.7" right="0.7" top="0.75" bottom="0.75" header="0.3" footer="0.3" />
    <pageSetup paperSize="9" orientation="portrait" r:id="rId1" />
</worksheet>

A1とB2セルにデータが含まれているのが分かりますね。ですが、謎の数字0と1があるだけで、内容は特には記述されていません。

テキスト情報はどこに行ったのでしょう？

その答えはShared String Table（SST、sharedStrings.xml）の中にあります。

`xl\sharedStrings.xml`

SSTはその名の通り、複数の場所から参照されるテキスト情報を格納するためテーブルです。

上記の例だとシートはSSTのインデックス番号を参照していたことになります。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" count="2" uniqueCount="2">
    <si>
        <t>Hello Excel</t>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>こんにちはExcel</t>
        <phoneticPr fontId="1" />
    </si>
</sst>

なお、文字情報は必ずSSTに格納しなければならない訳ではなく、Excelを出力するライブラリはシートのXMLに直接文字を格納する場合が多いです。

Excelファイルの読み込み

というわけで、Excelの深淵を覗く準備ができたところでread_files関数でファイルを読み込んでみましょう。

単純な例

以下のような単純なExcelファイルを用意します。

最低限のオプションだけ設定すると以下のように出力されます。

SELECT
  *
FROM
  read_files(
    "/Volumes/excel_read_files/default/files/01_simple_files.xlsx",
    format => "excel",
    schemaEvolutionMode => "none"
  )

スキーマを推論してくれるので、日付や数字もそれぞれの型として認識してくれています。

ですが、小数が少し怪しいですね。内部的にはこの形で格納されているので、read_files関数が悪いわけではなさそうです。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<worksheet>
    <sheetData>
        <row r="1" spans="1:4">
            <c r="C1">
                <v>1.1000000000000001</v>
            </c>
        </row>
        <row r="2" spans="1:4">
            <c r="C2">
                <v>2.2000000000000002</v>
            </c>
        </row>
        <row r="3" spans="1:4">
            <c r="C3">
                <v>3.3</v>
            </c>
        </row>
        <row r="4" spans="1:4">
            <c r="C4">
                <v>4.4000000000000004</v>
            </c>
        </row>
        <row r="5" spans="1:4">
            <c r="C5">
                <v>5.5</v>
            </c>
        </row>
    </sheetData>
</worksheet>

型が既知なのであれば、あらかじめスキーマヒントを与えておいたほうが良いかもしれません。

SELECT
  *
FROM
  read_files(
    "/Volumes/excel_read_files/default/files/01_simple_files.xlsx",
    format => "excel",
    schemaEvolutionMode => "none",
    schemaHints => "_c2 decimal(5,1)"
  )

ちなみに、inferColumnTypesはExcel読み込みでは考慮されないようです。

SELECT
  *
FROM
  read_files(
    "/Volumes/excel_read_files/default/files/01_simple_files.xlsx",
    format => "excel",
    schemaEvolutionMode => "none",
    inferColumnTypes => false
  )

スキーマヒントを与えて強制的に文字列とすると、to_stringをしたような形式になります。

また、日付はMM/DD/YY形式になります。USロケールなのかもしれません。

SELECT
  *
FROM
  read_files(
    "/Volumes/excel_read_files/default/files/01_simple_files.xlsx",
    format => "excel",
    schemaEvolutionMode => "none",
    schemaHints => "_c1 string, _c2 string, _c3 string"
  )

日本語を含む例

次はよくオフィスで流通していそうなファイルを読み込んでみます。

今回の検証で初めて知ったのですが、Excelは変換時の元テキストをフリガナとして格納してくれるっぽいです。

関係ないセルを読まないよう、dataAddressで読み込む場所を明示してあげます。

SELECT
  *
FROM
  read_files(
    "/Volumes/excel_read_files/default/files/02_日本語を含むファイル.xlsx",
    dataAddress => "'お供　給与表'!B2:C5",
    headerRows => 1,
    format => "excel",
    schemaEvolutionMode => "none"
  )

良くないですね。 フリガナも拾ってきてしまっています。

少なくとも日本語だと意図してフリガナを拾ってほしいケースはあまりないと思うので、GAまでにフリガナを拾わないか、オプションで選択出来るようになるといいなと思います。

ちなみに、この例だとSSTはこのようになっています。シート名として入力したテキストもフォネティックを拾っているとは思いませんでした。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" count="8" uniqueCount="8">
    <si>
        <t>お供</t>
        <rPh sb="1" eb="2">
            <t>トモ</t>
        </rPh>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>きび団子支給数</t>
        <rPh sb="2" eb="4">
            <t>ダンゴ</t>
        </rPh>
        <rPh sb="4" eb="7">
            <t>シキュウスウ</t>
        </rPh>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>猿</t>
        <rPh sb="0" eb="1">
            <t>サル</t>
        </rPh>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>犬</t>
        <rPh sb="0" eb="1">
            <t>イヌ</t>
        </rPh>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>雉</t>
        <rPh sb="0" eb="1">
            <t>キジ</t>
        </rPh>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>令和8年1月17日改定</t>
        <rPh sb="0" eb="2">
            <t>レイワ</t>
        </rPh>
        <rPh sb="3" eb="4">
            <t>ネン</t>
        </rPh>
        <rPh sb="5" eb="6">
            <t>ガツ</t>
        </rPh>
        <rPh sb="8" eb="9">
            <t>ニチ</t>
        </rPh>
        <rPh sb="9" eb="11">
            <t>カイテイ</t>
        </rPh>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>※変更時はおじいさんとおばあさんの承認を得ること</t>
        <rPh sb="1" eb="4">
            <t>ヘンコウジ</t>
        </rPh>
        <rPh sb="17" eb="19">
            <t>ショウニン</t>
        </rPh>
        <rPh sb="20" eb="21">
            <t>エ</t>
        </rPh>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>全然関係ないデータ</t>
        <rPh sb="0" eb="4">
            <t>ゼンゼンカンケイ</t>
        </rPh>
        <phoneticPr fontId="1" />
    </si>
</sst>

手動でフリガナを消してあげると意図した感じに取り込んでくれます。

ただし、手動で消すのは結構めんどくさいので、前処理でフリガナを消すプログラムを動かすとかでしょうか・・・

SELECT
  *
FROM
  read_files(
    "/Volumes/excel_read_files/default/files/03_日本語を含むファイル_フリガナ除去.xlsx",
    dataAddress => "'お供　給与表'!B2:C5",
    headerRows => 1,
    format => "excel",
    schemaEvolutionMode => "none"
  )

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" count="8" uniqueCount="8">
    <si>
        <t>令和8年1月17日改定</t>
        <rPh sb="0" eb="2">
            <t>レイワ</t>
        </rPh>
        <rPh sb="3" eb="4">
            <t>ネン</t>
        </rPh>
        <rPh sb="5" eb="6">
            <t>ガツ</t>
        </rPh>
        <rPh sb="8" eb="9">
            <t>ニチ</t>
        </rPh>
        <rPh sb="9" eb="11">
            <t>カイテイ</t>
        </rPh>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>※変更時はおじいさんとおばあさんの承認を得ること</t>
        <rPh sb="1" eb="4">
            <t>ヘンコウジ</t>
        </rPh>
        <rPh sb="17" eb="19">
            <t>ショウニン</t>
        </rPh>
        <rPh sb="20" eb="21">
            <t>エ</t>
        </rPh>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>全然関係ないデータ</t>
        <rPh sb="0" eb="4">
            <t>ゼンゼンカンケイ</t>
        </rPh>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>お供</t>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>きび団子支給数</t>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>猿</t>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>犬</t>
        <phoneticPr fontId="1" />
    </si>
    <si>
        <t>雉</t>
        <phoneticPr fontId="1" />
    </si>
</sst>

計算式を含む例

次は式を含むExcelファイルを読み込ませてみます。

ドキュメントページでは評価された数式を取り込みますとありますが、どのような意味なのでしょうか。

SELECT
  *
FROM
  read_files(
    "/Volumes/excel_read_files/default/files/04_formula.xlsx",
    format => "excel",
    schemaEvolutionMode => "none"
  )

エクセルで数式セルを作成すると、内部的には数式と共に計算済みの値が格納されています。ドキュメントの「評価された数式を取り込みます」とはおそらく内部的に保持されている計算済みの値を取り込むということを言っているのだと思われます。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<worksheet>
    <sheetData>
        <row r="1" spans="1:3">
            <c r="A1">
                <v>1</v>
            </c>
            <c r="B1">
                <v>2</v>
            </c>
            <c r="C1">
                <f>A1+B1</f>
                <v>3</v>
            </c>
        </row>
    </sheetData>
</worksheet>

では、計算済みの値が格納されないケースがあるのでしょうか。

全部のケースを確認した訳ではありませんが、ライブラリを使用してExcelファイルをプログラムから作成する場合は数式のみが格納されて計算済みの値が格納されない場合が多いです。

たとえば、以下のようなコードを使用して上記のExcelと同じようなファイルを作成したとします。

import openpyxl


def main():
    wb = openpyxl.Workbook()
    sheet = wb.active

    for it in range(1, 5):
        sheet.cell(it, 1).value = it
        sheet.cell(it, 2).value = it + 1
        sheet.cell(it, 3).value = f"=A{it}+B{it}"

    wb.save("05_formula_no_value.xlsx")


if __name__ == "__main__":
    main()

Excelで開くと未計算のセルは計算されて表示されますが、read_files関数では計算済みの値が無いため、正しく取得できていません。

SELECT
  *
FROM
  read_files(
    "/Volumes/excel_read_files/default/files/05_formula_no_value.xlsx",
    format => "excel",
    schemaEvolutionMode => "none"
  )

複数のファイル

問題ないとは思いますが、念のため複数のファイルの読み込みを試してみます。

以下のようなコードで100行×100ファイルのExcelを生成して読み込んでみます。

import random
import string

import openpyxl


def randomname(n):
    return "".join(random.choices(string.ascii_letters + string.digits, k=n))


def main():
    for i in range(1, 101):
        print(f"06_excel_files\\book_{i:0>3}.xlsx")
        wb = openpyxl.Workbook()
        sheet = wb.active

        for r in range(1, 101):
            sheet.cell(r, 1).value = i
            sheet.cell(r, 2).value = r

            for c in range(3, 6):
                sheet.cell(r, c).value = randomname(10)

            for c in range(6, 9):
                sheet.cell(r, c).value = random.randint(0, 100)

        wb.save(f"06_excel_files\\book_{i:0>3}.xlsx")


if __name__ == "__main__":
    main()

SELECT
  *
FROM
  read_files(
    "/Volumes/excel_read_files/default/files/06_excel_files/",
    format => "excel",
    schemaEvolutionMode => "none"
  )

良さそうですね。

サイズの大きいファイル

JavaでExcelを読み書きする代表的なライブラリと言えばApache POIがあります。

POIはUser API（Excelファイルをインメモリで展開するAPI）で巨大なファイルを扱おうとするとOOMでプログラムが爆散するという悲しき事故が発生しがちです。

SparkはScala、すなわちJVMで動作するので同じ事故が発生するか否かは割と気になりますよね。

以下のようなコードでそれぞれの行数を持つExcelファイルを作って、順番に読み込ませてみます。

import random
import string

import openpyxl

ROWS = [
    10000,
    10100,
    10101,
    10102,
    10103,
    10104,
    10105,
    10106,
    10107,
    10108,
    10109,
    10110,
    10120,
    10130,
    10140,
    10150,
    10160,
    10170,
    10180,
    10190,
    10200,
    10300,
    10400,
    10500,
    11000,
]


def randomname(n):
    return "".join(random.choices(string.ascii_letters + string.digits, k=n))


def main():
    for row_count in ROWS:
        print(f"07_large_excel_files\\book_{row_count}.xlsx")
        wb = openpyxl.Workbook()
        sheet = wb.active

        for r in range(1, row_count + 1):
            sheet.cell(r, 1).value = row_count
            sheet.cell(r, 2).value = r

            for c in range(3, 6):
                sheet.cell(r, c).value = randomname(10)

            for c in range(6, 9):
                sheet.cell(r, c).value = random.randint(0, 100)

        wb.save(f"07_large_excel_files\\book_{row_count}.xlsx")


if __name__ == "__main__":
    main()

詳細は省きますが、私の環境では10102行のファイルまでなら読み込んでくれましたが、10103行のファイルからは関数が返ってこなくなりました。

関数の内部的な制限に引っかかったのか、それともDatabricks Free Editionのなんらかのレートリミットに引っかかったのかは分かりませんが、あまり大量の行数を有するファイルの読み込みには向かないようです。

おわりに

いくつか気になる点はありましたが、ベータ版の機能なのでGAまでには修正されると思います。

Pythonでロジックを書かなくてもいい感じにExcelファイルが読み込めると、ファイルサーバ内に眠っているExcelファイルのデータの利活用のハードルも低くなると思います。

GAが待ち遠しい機能ですね。

jyuch / excel-read-files

余談

ファイルをドラッグアンドドロップでテーブルを作れる機能も内部的にread_files関数を使っているのか、現時点では同様に日本語のフリガナを拾ってしまいます。

こちらも解決済みです。やったぜ

おわり

2025年の振り返りとか

2025-12-31T00:00:00Z

はじめに

2025年の振り返りです。

Databricks

今年はお仕事でDatabricksをかなり触ってきました。

特にDatabricksの環境を完全にゼロから（新規契約のAWSアカウントから）構築するのはあまりない経験だと思うので、珍しい経験が出来たなと思います。

他にも基幹システムからのデータ取り込みやデータ加工パイプラインの構築・ガバナンス設計など~~運用の全部を一人でやらさせられてる~~大変貴重な経験を積ませていただいており大変うれしく思います。

個人的にはDatabricksは少なくとも数年はデータとAI領域でのトップを走るプロダクトだと思っているので、しばらくはDababricksのお仕事を続けたいなとは思ってます。

生成AI

データ基盤を触っているとAI絡みのお話を頂くので、RAGやプロンプト自動最適化などのテクノロジはちょこちょこと触っていました。特にDSPyとMLflowはかなり注目しているので、2026年もこれらのプロダクトを追いかけたいと思っています。

ただ、AIエージェントは技術的な領域としては面白いのですが、全社的なワークロードを動かしたときの性能面・コスト面の監視や基幹システムとの連接など考えないといけないことが多いなと現時点でも感じています。 2026年はこの辺の本格的な開発・運用が始まりそうなので2026年はつらみポイントが高い年になりそうです。

この辺を真面目にやろうとすると事業会社の内部でどうこう出来るレベルを超えそうと思っているのですが、皆さんどう考えてるんでしょうね？

資格とか

今年はネットワークスペシャリスト試験とSAAの2つを合格・取得できました。

ネットワークスペシャリスト試験で勉強した内容は普通に日常の業務~~やテキトーなことを吹っ掛けてくる自称有識者をボコすの~~に役に立つので、ネットワークに触る人はみんな勉強すると良いと思います。

IPAの試験体系が改定されて高度試験が消える前にデータベーススペシャリストもとっておこうかなと思ってます。セキュリティスペシャリストはどうなるんでしょうね？あれだけ体系が違うっぽいので残る気がしますが。

AWS系の資格について特にコンプとかは考えていないのですが、SAPを持ってると貰えるお小遣いが増えるので受けてもいいかなと思っています。まぁ、弊社は全体的に資格難易度と金額が明らかに乖離しているのでにゃーん（社会性フィルタ）

また、Databricks Certified Data Engineer Associateとかはあまり難しくなさそうなので試しに取ってみたいなとは思ってるのですが、受験料がｸｯｿ高いのと、弊社内でお小遣いが貰える資格ではないのでちょっと迷ってます。

コミュニティ

東京に勤務することになってから今年はDatabricksのユーザグループであるJEDAIのミートアップから始まり、結構な数の勉強会やもくもく会にお邪魔させていただきました。

とくにIbaraki.devにおかれましては、いきなりDNSの話をし始めたり誰も使ってないDNSのライブラリの話をし始めたりと大変ご迷惑をお掛けしました。

いろんな人と交流するとそれぞれの組織の考え方が分かったり、どんな組織でも大体似たようなことで悩んでるんだなというのが分かって楽しいですね。

おわりに

2026年も飛躍の年にしたいですね。

おわり

ダウナー系生成AIに毎日カスの嘘を流し込まれたい

2025-12-28T00:00:00Z

はじめに

最近は仕事でもAIエージェントの話を聞くことが多くなってきました。

AIエージェントの性能はプロンプトの記述で大きく変わってきます。ですが、プロンプトが少し変わったり、ナレッジカットオフが変わっただけで挙動が大きく変わるなんて話も聞きます。

プロンプトの人力での調整はつらみポイントがとても高いので、個人的にはDSPyのようなプロンプト自動最適化に大きな期待を寄せています。

そこで、今回は与えられたキーワードからいわゆる「カスの嘘」を生成するためのプロンプトをDSPyを使っての最適化を試してみます。

カスの嘘

まず、生成AIに生成させたいカスの嘘の要件を確認してみましょう。

ここで生成したいカスの嘘とは以下のようなものです。

雀が電線で感電しないのは、みんなで乗ることでダメージを分散しているからなんだよ
地球儀は風水で最強なので、どこにいくつ置いてもいいんだよ
一度開封したみりんを常温で保管すると、違法なんだって

これらのカスの嘘の特徴をまとめてみると、

一見して分かるようなあからさまな嘘ではないこと
科学・文化・法律に依拠したうそであること
「〇〇、〇〇」のフォーマットに従っており、20文字から40文字程度であること
落ち着いた穏やかな口調であること

であることが分かります。

DSPyを使用した最適化

手作業でのプロンプトの最適化では、上記に挙げた特徴に沿った出力を行うようにプロンプトを手作業で最適化する必要があります。

DSPyでは代わりに生成AIを使用した処理をシグネチャとモジュールとして定義し、用意したデータセットと評価関数をを用いてスコアが高くなるようにプロンプトの最適化を行います。

今回使用するGEPAでは評価関数のメトリックだけでなく、評価関数が返すフィードバックテキストを元にプログラムの最適化を行います。

カスの嘘を吐くDSPyプログラム

今回は以下のようなシグネチャとモジュールを定義します。キーワードからカスを嘘を出力するとても単純なものです。

また、DSPyではコメントドキュメントをプロンプトとして使用するのですが、自動プロンプト最適化を使用する場合は非常に非常にざっくりとしたものでもいい感じに最適化してくれます。

class LieGenerate(dspy.Signature):
    """与えられたキーワードからカスの嘘を生成します"""

    keyword: str = dspy.InputField(desc="キーワード")
    lie: str = dspy.OutputField(desc="生成されたカスの嘘")


class GenerateLie(dspy.Module):
    def __init__(self):
        super().__init__()
        self.extractor = dspy.ChainOfThought(LieGenerate)

    def forward(self, keyword):
        return self.extractor(keyword=keyword)

評価関数

今回はカスの嘘を上記の観点で判定させるため、LLM as Judgeで評価を行います。

生成AIは放っておくとファンタジーな嘘をつき始めるので、ファンタジー要素はあからさまなSF要素は減点するように評価をさせています。

この評価用のプロンプトはある程度試行錯誤しないといけないんですよね・・・

def create_lie_metric(reflection_lm: dspy.LM):
    class StyleEvaluation(dspy.Signature):
        """応答のスタイルを評価"""

        response = dspy.InputField(desc="評価対象の応答")
        criteria = dspy.InputField(desc="評価基準")
        score = dspy.OutputField(desc="スコア（0-20）", format=int)
        explanation = dspy.OutputField(desc="詳細な項目毎のスコアとその理由")

    evaluator = dspy.ChainOfThought(StyleEvaluation)

    def lie_metric(gold, pred, trace=None, pred_name=None, pred_trace=None):
        criteria = """
        以下の基準で0-20点で評価してください:
        1. キーワードに沿った嘘となっているか（2点）
        2. 20-60文字で、「〇〇は、〇〇」や「〇〇はね、〇〇」という形式となっているか（2点）
        3. あからさまな嘘ではなく、一見すると嘘とわからないようなもっともらしい嘘となっているか（6点）
            - 魔法やドラゴン・妖精といった空想的存在に基づいた嘘ではないか
            - 宇宙人や火星といった存在が確認されていないものや現在の科学水準で達成できない事柄を含んでいないか
            - 食品が必修科目として学ばれるなど、キーワードと嘘の内容が乖離していないか
            - 存在しない税が免除されるといった一つの文の中に複数の嘘が入っている場合は減点
        4. 余計な解説や文が入っておらず、嘘のみの出力となっているか（2点）
        5. 語頭に「ね、知ってる？」や「実は」を適切に使っているか（2点）
        6. 語尾に「（な）んだよ」や「（な）んだって」、「らしいよ」を自然に接続して適切に使っているか（2点）
        7. 日本語として自然で読みやすいか（2点）
        8. 穏やかで落ち着いた口調か（2点）
        """
        with dspy.context(lm=reflection_lm):
            eval_result = evaluator(response=pred.lie, criteria=criteria)
            score = min(20, max(0, float(eval_result.score))) / 20.0
            explanation = eval_result.explanation
            return dspy.Prediction(score=score, feedback=explanation)

    return lie_metric

最適化

今回はリフレクションLLMにclaude-sonnet-4-5-20250929を使用し、タスクを実行するためのLLMとして以下のモデルを使って評価をします。

claude-haiku-4-5-20251001
gpt-oss-120b
gpt-oss-20b

本当は Claude Opus 4.5 を使いたかったのですが、トレーニングを1回通しで実行するだけで50ドルくらい消費しそうになったためビビッて Sonnet に変えたという経緯があります。

学習1回あたり2時間30分程度、コストとしては10ドル程度掛かっていました。

生成出来るカスの嘘

各モデルがつく嘘は以下のような感じです。

gpt-ossはやたら江戸時代の話題をしたがりますが、全体的にそれっぽい嘘をつけているのではないでしょうか。

symbol	keyword	lie
gpt-oss-120b	おみくじ	実は、おみくじは江戸時代に寺の守護神が結果を予測したんだって
gpt-oss-20b	おみくじ	おみくじは、実は江戸時代に寺院で神の預言として引かれたものらしいよ
haiku-4-5	おみくじ	実は、おみくじは元々、神社の祭りの日に参加者の役割を決めるためのくじだったんだって
gpt-oss-120b	お餅	実は、お餅は江戸時代に、米ではなく大麦の粉を蒸して作っていたらしいよ
gpt-oss-20b	お餅	お餅は、実は江戸時代の神社で祭祀用の供え物として使われていたんだよ
haiku-4-5	お餅	実は、お餅は昔、神社の儀式で使う供え物として作られたのが始まりで、食べ物として広まったのは江戸時代らしいよ
gpt-oss-120b	ちくわ	ちくわは実は江戸時代に、魚のすり身ではなく、山形県の里山で取れた大根の根を乾燥させたものらしいよ
gpt-oss-20b	ちくわ	ちくわは、実は平安時代の貴族が魚の内臓を使い、皮を巻いて焼いたお菓子らしいよ
haiku-4-5	ちくわ	実は、ちくわは昔、竹の筒に詰めて蒸すことから『竹輪』という名前がついたんだって
gpt-oss-120b	チョコレート	チョコレートは実は19世紀末のスイスで、当初はカカオ豆の発酵を防ぐための保存料として開発されたらしいよ
gpt-oss-20b	チョコレート	チョコレートは、実は16世紀にスペインの商人が日本に持ち込んだ貴族用甘味料として使われていたんだよ
haiku-4-5	チョコレート	実は、チョコレートは昔、王族の儀式用の飲料として神聖視されていたんだって
gpt-oss-120b	懐中電灯	懐中電灯は実は、第一次世界大戦時にドイツ軍が潜水艦用に赤外線光源を内蔵していたらしいよ
gpt-oss-20b	懐中電灯	懐中電灯は、実は江戸時代に武士が夜の暗闇で作戦指示を確認するために携帯した小型の灯りで、取手に銀の刻印が付いていたんだよ
haiku-4-5	懐中電灯	実は、懐中電灯は元々、鉱山での作業中に両手を自由にするために懐に入れて使う照明として開発されたんだって
gpt-oss-120b	乾電池	実は、乾電池はかつて日本の昭和30年代に、アルカリ電解質ではなく銀酸化物が主成分だったらしいよ
gpt-oss-20b	乾電池	乾電池は、実は地下鉄の電力供給に使われていたと、当時の軍部秘書が記録していたんだよ
haiku-4-5	乾電池	実は、乾電池は元々、懐中電灯ではなく、医療用の刺激装置として開発されたんだって
gpt-oss-120b	軽トラ	実は、軽トラは昭和60年代に農業用から貨物輸送専用に改良されたんだって
gpt-oss-20b	軽トラ	軽トラは、実は昭和30年代に発明された、山間部の農家が手作りで改造した小型自動車の原型だって
haiku-4-5	軽トラ	実は、軽トラは元々、郵便配達員が使うために開発された専用車両なんだって
gpt-oss-120b	初詣	実は、初詣は江戸時代に商人が売り上げを祈願するために始めたらしいよ
gpt-oss-20b	初詣	初詣は、実は江戸時代から新年のご飯をお供えすると、その年の収穫が倍増すると信じられていたらしいよ
haiku-4-5	初詣	実は、初詣は江戸時代に商人たちが商売繁盛を祈るために始めた習慣なんだって
gpt-oss-120b	生成AI	生成AIは実は1970年代に日本の研究所で、音声合成だけでなく感情推定までできると宣伝されたらしいよ
gpt-oss-20b	生成AI	生成AIは、実は19世紀末のドイツ工学者がパターン生成装置として開発したらしいよ
haiku-4-5	生成AI	実は、生成AIって、元々は人間の脳の神経回路を模倣するために開発された技術なんだって
gpt-oss-120b	東京タワー	実は、東京タワーは当初、通信塔ではなく観測用の気象観測所として建てられたらしいよ
gpt-oss-20b	東京タワー	東京タワーは、実は昭和初期に東京郊外の灯台の設計図を活用して作られたらしいよ
haiku-4-5	東京タワー	実は、東京タワーは元々、戦後の電波障害を調査するための実験施設だったんだって

クロス評価

それぞれのモデルに最適なプロンプトが求められたので、プロンプトをそれぞれモデルに適用してスコアがどのようになるか評価してみました。

どのモデルでもモデルに最適化されたプロンプトを使用したときが最も高いスコアを出していることが分かります。また、gpt-oss-20bのようにパラメータ数が小さいモデルでは最適なプロンプトとそれ以外のプロンプトでのスコアの差が大きくなることが分かります。

一通り試してみての感想

ここからは一通り試してみての感想です。

学習データの準備が一番大変

この辺はよく言われると思います。今回はしょうもない嘘をつかせるという非常に単純なタスクだったので、学習データは30程度でも割と何とかなってます。ですが、業務レベルの複雑さの場合、とにかく学習データを用意するのがとても大変になると思います。

評価関数のチューニングが大事

今回のタスクはキーワードから嘘をつくという、創作的なタスクを行わせています。そのため、与えられた入力からどれだけ期待する出力化という観点では評価がしづらく、LLM as Judgeで評価をさせています。

評価関数で自分が欲しい嘘に対して高いスコアを返せるよういかに嘘の条件を言語化してLLM as Judgeで評価するのが大事でした。

APIの使用料金もそれなりに掛かる

GEPAはフィードバックを基にプロンプトを最適化しますが、そのプロンプトの最適化には出来るだけ高性能なLLMを使ったほうがいいらしいです。

そんな高性能なLLMをすごい勢いで呼び出すので、当然APIの使用料金も高くなります。かといってプロンプトの最適化に安価なモデルを使用すると明らかにカスの嘘のクオリティも下がるので、この辺はクオリティと費用のバランスをうまくとる必要がありそうです。

試行錯誤が無くなるわけではない

LLM as Judgeを使う以上、ジャッジをさせるプロンプトそのものの最適化は人間がやらなくてはいけません。今回の例ですと、LLMはやたらとファンタジーな嘘をつきたがるので、それをいかにフィードバックで消すかというところに労力がかかっています。

LLM as Judge自体をMIPROなりGEPAなりで最適化する手法もありますが、その辺の評価をどうするかや学習データの整備にも手間と時間が掛かるので、試行錯誤自体を消せるわけではないのかなという気がしています。

おわりに

生成AIにしょうもない嘘をつかせるのも安くはないですね・・・

jyuch / dspy-kasu-no-uso

おわり

参考資料

DSPyを使用してLLMを使ったレシートの読み取り精度を向上させたい

2025-10-26T00:00:00Z

はじめに

簡単な家計簿をつけているのですが、レシートの内容を確認して転記するのがめんどくさいなと感じていました。

そこで、LLMを使って情報を抽出できないかなと考えていたのですが、せっかくならDSPyを使って構造化出力するのと、プロンプト最適化を行ってみたいなということで試してみました。

シグネチャの準備

DSPyでは入力値と出力値をコードとして表現します。ここではレシート画像から購入日と合計金額を抽出することにします。

入力値と出力値はシグネチャとして表現され、dspy.Signatureのサブクラスとして実装します。

from datetime import date

import dspy


class ExtractReceiptInfo(dspy.Signature):
    """Extract total amount from receipt image."""

    image: dspy.Image = dspy.InputField(desc="Receipt image.")
    purchase_date: date = dspy.OutputField(desc="Purchase date of payment.")
    total_amount: int = dspy.OutputField(desc="Total amount of payment.")


class ReceiptExtractor(dspy.Module):
    def __init__(self):
        super().__init__()
        self.extractor = dspy.ChainOfThought(ExtractReceiptInfo)

    def forward(self, image):
        return self.extractor(image=image)


def extraction_metric(gold, pred, trace=None):
    metric = 0

    if gold.total_amount == pred.total_amount:
        metric += 1
    if gold.purchase_date == pred.purchase_date:
        metric += 1

    if trace is None:
        return metric / 2.0
    else:
        return metric == 2

学習データの準備

DSPyでは教師データを使用して入力データから期待する出力をするようにプロンプトを最適化します。

そのため、最初にある程度のレシート画像と、その画像からどのような結果を出力してほしいかの期待値をひたすら列挙する必要があります。

ここでは、以下のような教師データを家中のあるだけのレシートを使って作成します。スキャナでレシートを読み込み、エクセルでレシート画像と期待値の組み合わせをひたすら入力します。

このデータそのまま家計簿に突っ込めばよくね？とか考えてはいけません。

image	purchase_date	total_amount
20251019_000.jpg	2025-08-28	162
20251019_001.jpg	2025-08-19	170
20251019_002.jpg	2025-09-09	162
...	...	...

LM Studioの準備

タスクを実行するLLMはLM Studioを使ってローカルで実行するので、LM Studioをインストールしておきます。モデルはGemma 3を使います。

Databricks Free Editionの準備

MIPROv2では教師として高性能なLLMを使用するのですが、ここではDatabricksでホストされているLlama 4 Maverickを利用します。

Databricks Free Editionではレートリミットなどの制限はありますが、無償で使わせてくれるのでありがたく使います。Databricksさんはなんて太っ腹なんでしょう！（ステマその１）

Settings → User → Developer → Access tokensからトークンを発行しておきます。また、MLFlowも使いたいので、併せてExperimentsも作成しておきます。 Experimentsを作成すると、外部からExperimentsを使うにはみたいな画面が表示されるので、表示された環境変数をコピーしておきます。

最終的に以下の環境変数を登録します。

環境変数	例
`DATABRICKS_API_BASE`	`https://dbc-12345678-abcd.cloud.databricks.com/serving-endpoints`
`DATABRICKS_API_KEY`	Databricksのシークレット
`DATABRICKS_HOST`	`https://dbc-12345678-abcd.cloud.databricks.com`
`DATABRICKS_TOKEN`	Databricksのシークレット
`MLFLOW_EXPERIMENT_ID`	`123456789012345`
`MLFLOW_REGISTRY_URI`	`databricks-uc`
`MLFLOW_TRACKING_URI`	`databricks`

DATABRICKS_API_BASEとDATABRICKS_API_KEYはDatabricksのServing endpointsにアクセスする用で、それ以外はMLFlowにメトリックを送る用です。

トレーニング

必要なものがそろったらいよいよプロンプト最適化を実行します。ここではとりあえずMIPROv2を使っていきます。

余談ですが、DSPyはLLMにアクセスするためにLiteLLMというライブラリを使用しているようです。

LiteLLMではプレフィックスでどのプロバイダーのAPI形式（OpenAI互換やAnthropic互換など）を判断しているようです。また、LM StudioはOpenAI互換です。

そのため、OpenAI互換としてAPIを叩いてほしいのですが、openai/google/gemma-3-12bとかいう各方面から怒られそうなモデル名で指定をしないといけません。

import csv
import os
from datetime import datetime
from typing import List

import dspy
import mlflow

from program import ReceiptExtractor, extraction_metric

LMSTUDIO_API_BASE = os.environ["LMSTUDIO_API_BASE"]

teacher_llm = dspy.LM(
    "databricks/databricks-llama-4-maverick",
    temperature=1.0,
)

student_llm = dspy.LM(
    "openai/google/gemma-3-12b",
    api_base=LMSTUDIO_API_BASE,
    api_key="dummy",
)


def run_prompt_optimizer(train_examples: List[dspy.Example]):
    student_program = ReceiptExtractor()
    optimizer = dspy.MIPROv2(
        metric=extraction_metric, prompt_model=teacher_llm, task_model=student_llm
    )
    compiled_program = optimizer.compile(student_program, trainset=train_examples)
    compiled_program.save("./program.json", save_program=False)


def main():
    mlflow.dspy.autolog(
        log_compiles=True,
        log_evals=True,
        log_traces_from_compile=True,
    )

    dspy.configure(lm=student_llm)

    train_examples: List[dspy.Example]
    with open("./dataset/training.csv", encoding="utf_8") as f:
        reader = csv.DictReader(f)
        train_examples = [
            dspy.Example(
                image=dspy.Image.from_file(f"./dataset/{row['image']}"),
                purchase_date=datetime.strptime(
                    row["purchase_date"], "%Y-%m-%d"
                ).date(),
                total_amount=int(row["total_amount"]),
            ).with_inputs("image")
            for row in reader
        ]

    run_prompt_optimizer(train_examples)


if __name__ == "__main__":
    main()

評価

学習が終わったら、とりあえずどのくらい違うのか評価してみましょう。

ここでは、学習前と学習後、LLMのモデル、パラメータ数を変えてどのくらい差があるのかを確認しています。

import csv
import os
from datetime import datetime
from typing import List

import dspy
from dspy.evaluate.evaluate import Evaluate

from program import ReceiptExtractor, extraction_metric

LMSTUDIO_API_BASE = os.environ["LMSTUDIO_API_BASE"]

gemma_3_12b = dspy.LM(
    "openai/google/gemma-3-12b",
    api_base=LMSTUDIO_API_BASE,
    api_key="dummy",
)

gemma_3_27b = dspy.LM(
    "openai/google/gemma-3-27b",
    api_base=LMSTUDIO_API_BASE,
    api_key="dummy",
)

llama_4_maverick = dspy.LM(
    "databricks/databricks-llama-4-maverick",
)


def main():
    dspy.configure(lm=gemma_3_12b)
    original = ReceiptExtractor()
    trained = ReceiptExtractor()
    trained.load("./program.json")

    train_examples: List[dspy.Example]
    with open("./dataset/training.csv", encoding="utf_8") as f:
        reader = csv.DictReader(f)
        train_examples = [
            dspy.Example(
                image=dspy.Image.from_file(f"./dataset/{row['image']}"),
                purchase_date=datetime.strptime(
                    row["purchase_date"], "%Y-%m-%d"
                ).date(),
                total_amount=int(row["total_amount"]),
            ).with_inputs("image")
            for row in reader
        ]

    evaluate = Evaluate(
        devset=train_examples, num_threads=1, display_progress=True, display_table=0
    )

    with dspy.context(lm=gemma_3_12b):
        evaluate(original, metric=extraction_metric)
        evaluate(trained, metric=extraction_metric)

    with dspy.context(lm=gemma_3_27b):
        evaluate(original, metric=extraction_metric)
        evaluate(trained, metric=extraction_metric)

    with dspy.context(lm=llama_4_maverick):
        evaluate(original, metric=extraction_metric)
        evaluate(trained, metric=extraction_metric)


if __name__ == "__main__":
    main()

モデル	最適化前	最適化後
`google/gemma-3-12`	84.0%	96.2%
`google/gemma-3-27b`	80.2%	97.2%
`databricks-llama-4-maverick`	100.0%	100.0%

あー、うん、まぁ、ねぇ。

おわりに

プロンプト最適化の部分については確かに最適化すれば性能は上がりましたが、最初から高性能なモデルを使えばそりゃ精度は高いよねというのを如実に見せつけられました。

ですが、個人的には構造化出力をコードとして表現できるのはうれしみがありますね。プロンプトにJSON Schemaをくっつけて、出力をJSONパーサに食わせて正常にパース出来るのを祈るという作業から解放されるだけでもDSPyを使ううれしみがあると思います。

教師データだけ用意しておけば、他のLLMが出てきたときは最適化と検証のループを回して、今までよりも成績が良ければ入れ替えるというサイクルをほぼ自動で回せます。

ギョームでLLMを使う場合はこの辺のサイクルを回せるようにしておくと後々のつらみポイントを軽減出来ると思うので、みなさんDatabricksと合わせて使ってみてはいかがでしょうか。（ステマその２）

jyuch / extract-receipt

おわり

PostgreSQL 18 の uuidv7 関数は単調性が保証されているから安心だねってお話

2025-10-12T00:00:00Z

長いので先にまとめ

UUIDv7はRFC9562上ではミリ秒精度のタイムスタンプを持つことを要求している
また、オプショナルとしてrand_a及びrand_bの生成方法を工夫して単調増加を保証しても良いとされている
PostgreSQL 18 のuuidv7()関数はRFC9562のSection 6.2 Method 3で提案されているタイムスタンプをサブミリ秒まで拡張する方法で単調増加を保証している
- サブミリ秒レベルでタイムスタンプが衝突した場合は、最小精度でインクリメントすることでタイムスタンプの衝突を回避している

はじめに

最近リリースされたPostgreSQL 18 で UUIDv7 の生成がサポートされました。

個人的にはUUIDが生成順にソート可能になるうれしさがよく分からないのですが、いざ使うことになった際に困らないように調べてみることにしました。

UUIDv7

そもそも、UUIDv7はどのような構造をしているのでしょうか。

5.7. UUID Version 7からビットレイアウトを引用して確認してみましょう。

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           unix_ts_ms                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          unix_ts_ms           |  ver  |       rand_a          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |var|                        rand_b                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                            rand_b                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                   Figure 11: UUIDv7 Field and Bit Layout

バージョン（ver）とバリアント（var）を除くと、以下の要素から構成されていることが分かります。

フィールド	説明
`unix_ts_ms`	48ビットで表現されたミリ秒精度のUnixエポックタイムスタンプ
`rand_a`	12ビットのランダムフィールド
`rand_b`	62ビットのランダムフィールド

RFCが最低限求めている仕様では、タイムスタンプはミリ秒精度となっています。そのため、同一ミリ秒内で複数回UUIDが生成された場合、生成された順序の並べ替えを保証出来なくなってしまいます。

そのため、6.2. Monotonicity and Countersでは、高頻度でのUUIID生成環境下での単調増加性を保証するための方法が提案されています。

PostgreSQL 18 の UUIDv7

PostgreSQL 18 のuuidv7()関数はミリ秒タイムスタンプ + サブミリ秒タイムスタンプ + ランダム値で計算されていることがドキュメントに記載されています。

具体的にはuuid.cの以下のgenerate_uuidv7()関数で実装されています。

/*
 * Generate UUID version 7 per RFC 9562, with the given timestamp.
 *
 * UUID version 7 consists of a Unix timestamp in milliseconds (48 bits) and
 * 74 random bits, excluding the required version and variant bits. To ensure
 * monotonicity in scenarios of high-frequency UUID generation, we employ the
 * method "Replace Leftmost Random Bits with Increased Clock Precision (Method 3)",
 * described in the RFC. This method utilizes 12 bits from the "rand_a" bits
 * to store a 1/4096 (or 2^12) fraction of sub-millisecond precision.
 *
 * unix_ts_ms is a number of milliseconds since start of the UNIX epoch,
 * and sub_ms is a number of nanoseconds within millisecond. These values are
 * used for time-dependent bits of UUID.
 *
 * NB: all numbers here are unsigned, unix_ts_ms cannot be negative per RFC.
 */
static pg_uuid_t *
generate_uuidv7(uint64 unix_ts_ms, uint32 sub_ms)
{
	pg_uuid_t  *uuid = palloc(UUID_LEN);
	uint32		increased_clock_precision;

	/* Fill in time part */
	uuid->data[0] = (unsigned char) (unix_ts_ms >> 40);
	uuid->data[1] = (unsigned char) (unix_ts_ms >> 32);
	uuid->data[2] = (unsigned char) (unix_ts_ms >> 24);
	uuid->data[3] = (unsigned char) (unix_ts_ms >> 16);
	uuid->data[4] = (unsigned char) (unix_ts_ms >> 8);
	uuid->data[5] = (unsigned char) unix_ts_ms;

	/*
	 * sub-millisecond timestamp fraction (SUBMS_BITS bits, not
	 * SUBMS_MINIMAL_STEP_BITS)
	 */
	increased_clock_precision = (sub_ms * (1 << SUBMS_BITS)) / NS_PER_MS;

	/* Fill the increased clock precision to "rand_a" bits */
	uuid->data[6] = (unsigned char) (increased_clock_precision >> 8);
	uuid->data[7] = (unsigned char) (increased_clock_precision);

	/* fill everything after the increased clock precision with random bytes */
	if (!pg_strong_random(&uuid->data[8], UUID_LEN - 8))
		ereport(ERROR,
				(errcode(ERRCODE_INTERNAL_ERROR),
				 errmsg("could not generate random values")));

#if SUBMS_MINIMAL_STEP_BITS == 10

	/*
	 * On systems that have only 10 bits of sub-ms precision,  2 least
	 * significant are dependent on other time-specific bits, and they do not
	 * contribute to uniqueness. To make these bit random we mix in two bits
	 * from CSPRNG. SUBMS_MINIMAL_STEP is chosen so that we still guarantee
	 * monotonicity despite altering these bits.
	 */
	uuid->data[7] = uuid->data[7] ^ (uuid->data[8] >> 6);
#endif

	/*
	 * Set magic numbers for a "version 7" (pseudorandom) UUID and variant,
	 * see https://www.rfc-editor.org/rfc/rfc9562#name-version-field
	 */
	uuid_set_version(uuid, 7);

	return uuid;
}

詳しくは実装を読んでもらえればと思いますが、rand_aフィールドの12bitにナノ秒（Linux）を埋め込むか、マイクロ秒 + ランダム値（Windows・mac）を埋め込んでいます。

また、現在時刻を供給しているget_real_time_ns_ascending()関数内で、前回との時刻の差分がrand_aフィールドに埋め込むタイムスタンプの精度以下の場合は、最小精度（Linuxの場合は245マイクロ秒）を加算することでサブミリ秒内でタイムスタンプが衝突することを防いでいます。

/*
 * Get the current timestamp with nanosecond precision for UUID generation.
 * The returned timestamp is ensured to be at least SUBMS_MINIMAL_STEP greater
 * than the previous returned timestamp (on this backend).
 */
static inline int64
get_real_time_ns_ascending()
{
	static int64 previous_ns = 0;
	int64		ns;

	/* Get the current real timestamp */

#ifdef	_MSC_VER
	struct timeval tmp;

	gettimeofday(&tmp, NULL);
	ns = tmp.tv_sec * NS_PER_S + tmp.tv_usec * NS_PER_US;
#else
	struct timespec tmp;

	/*
	 * We don't use gettimeofday(), instead use clock_gettime() with
	 * CLOCK_REALTIME where available in order to get a high-precision
	 * (nanoseconds) real timestamp.
	 *
	 * Note while a timestamp returned by clock_gettime() with CLOCK_REALTIME
	 * is nanosecond-precision on most Unix-like platforms, on some platforms
	 * such as macOS it's restricted to microsecond-precision.
	 */
	clock_gettime(CLOCK_REALTIME, &tmp);
	ns = tmp.tv_sec * NS_PER_S + tmp.tv_nsec;
#endif

	/* Guarantee the minimal step advancement of the timestamp */
	if (previous_ns + SUBMS_MINIMAL_STEP_NS >= ns)
		ns = previous_ns + SUBMS_MINIMAL_STEP_NS;
	previous_ns = ns;

	return ns;
}

そのため、実用的かどうかと言われるとｱﾚですが、uuidv7()関数で生成されたUUIDv7からサブミリ秒のタイムスタンプを抽出することが出来ます。

// サブミリ秒が12ビットで供給されている環境用
fn uuidv7_to_timestamp(uuidv7: &str) -> (i64, i64) {
    let uuid = uuidv7.replace("-", "");
    let uuid = u128::from_str_radix(&*uuid, 16).unwrap();
    let ms = (uuid >> 80) as i64;

    let uuid = uuid.to_be_bytes();
    let increased_clock_precision = (((uuid[6] & 0x0fu8) as i64) << 8) | uuid[7] as i64;
    let ns = increased_clock_precision * SUBMS_MINIMAL_STEP_NS;

    (ms, ns)
}

jyuch/pg-uuidv7-to-timestamp

PostgreSQL 18 でのUUIDv7生成例

最後に実際にuuidv7()関数を使ってUUIDv7を生成して、単調増加しているかを確認してみましょう。

以下のようなテーブルを作成したうえで、

create table uuidv7_test_table
(
    i     int,
    clock timestamp,
    value uuid
);

以下のクエリで全力でUUIDv7を生成します。

begin transaction;
do
$do$
  begin
    for i in 1..1000000
      loop
        insert into uuidv7_test_table(i, clock, value) 
        values (i, clock_timestamp(), uuidv7());
      end loop;
    end
$do$;
end;

すると、以下のような結果となります。上記のuuidv7_to_timestamp()の結果を併記しています。

select i, value, uuid_extract_timestamp(value), clock
from uuidv7_test_table
order by value;

i	value	uuid_extract_timestamp	clock	uuidv7_to_timestamp
1	0199d67d-81a7-713d-aed5-6bbd22a476c2	2025-10-12 03:36:13.479000 +00:00	2025-10-12 03:36:13.479071	2025-10-12 03:36:13.479 UTC 77665
2	0199d67d-81a7-7be4-ba18-b1d95ac5835f	2025-10-12 03:36:13.479000 +00:00	2025-10-12 03:36:13.479741	2025-10-12 03:36:13.479 UTC 745780
3	0199d67d-81a7-7c31-9ca1-df81b59c2e69	2025-10-12 03:36:13.479000 +00:00	2025-10-12 03:36:13.479762	2025-10-12 03:36:13.479 UTC 764645
4	0199d67d-81a7-7c45-b183-8ebf38326e24	2025-10-12 03:36:13.479000 +00:00	2025-10-12 03:36:13.479766	2025-10-12 03:36:13.479 UTC 769545
5	0199d67d-81a7-7c55-893a-c1685851f5f7	2025-10-12 03:36:13.479000 +00:00	2025-10-12 03:36:13.479770	2025-10-12 03:36:13.479 UTC 773465

uuid_extract_timestamp関数がミリ秒までの精度しか返していませんが、仕様上はミリ秒精度があれば良いとされていることと、外部で生成されたUUIDv7でも対応できるようにこのようになっています。

おわり

PostgreSQL 18 をソースコードからビルドしたい

2025-10-11T00:00:00Z

はじめに

PostgreSQL 18 がリリースされたので、ソースコードからビルドする手順を確認してみました。

まぁ、基本的には公式リファレンスと過去の自分のブログをなぞっているだけです。

LLVMのサポートと、lz4・zstd圧縮のサポートを有効にしてビルドします。

Chapter 17. Installation from Source Code

PostgreSQLを野良ビルドしてローカルインストールしたい

環境

ソフトウェア	バージョン
OS	Ubuntu 24.04.3 LTS
PostgreSQL	18.0

また、ソースコードは$HOME/srcに展開するものとし、バイナリは$HOME/.local/pg18.0にインストールするものとします。

コンパイラ・ライブラリのインストール

ビルドするだけなら以下のパッケージを入れるだけでOKです。

sudo apt install \
  build-essential \
  flex \
  bison \
  libreadline-dev \
  zlib1g-dev \
  liblz4-dev \
  libzstd-dev \
  llvm-20 \
  clang-20

ドキュメントを含めたフルビルドが必要なら以下のパッケージも必要になります。

sudo apt install \
  docbook-xml \
  docbook-xsl \
  libxml2-utils \
  xsltproc \
  fop

ソースコードのダウンロード・展開

以下のコマンドよりソースコードをダウロード・展開します。

cd $HOME/src
curl -OL https://ftp.postgresql.org/pub/source/v18.0/postgresql-18.0.tar.gz
tar zxvf postgresql-18.0.tar.gz

ビルド・インストール

以下のコマンドより、configureを流します。

cd postgresql-18.0
mkdir build_temp && cd build_temp
$HOME/src/postgresql-18.0/configure \
  --prefix=$HOME/.local/pg18.0 \
  --with-icu \
  --with-lz4 \
  --with-zstd \
  --with-llvm \
  LLVM_CONFIG='/usr/bin/llvm-config-20' \
  CLANG='/usr/bin/clang-20' \
  CC='/usr/bin/clang-20' \
  CXX='/usr/bin/clang-20'

バイナリ系をビルドするだけなら以下のコマンドを実行します。

make world-bin
make install-world-bin

ドキュメントを含めてすべてビルドするなら以下のコマンドを実行します。

make world
make install-world

おわり