/ /

クエリでの日時関数の使用

Overview

このガイドでは、非表示 ORM 用のMongoDB拡張機能を使用して、日付時刻フィールドで非表示クエリ言語（HQL）の extract() 関数と format() 関数を呼び出す方法を学習できます。 extract() を使用して日時値の一部を返すことができ、format() を使用して日時値を string としてレンダリングできます。

Hibernetes ORM 拡張機能は、各呼び出しを $project ステージのMongoDB集計式に変換します。 SELECT 句の日時フィールドでどちらの関数を呼び出すこともできます。

注意

タイムゾーン

Hibernetes ORM 拡張機能は、アプリケーションを実行するJVMのデフォルトのタイムゾーン内の各日時関数を解決します。そのゾーンは、生成された演算子の timezone 引数としてMongoDBに渡されます。同じクエリでは、異なるタイムゾーンで構成されたホストで異なる値が返される場合があります。

Hibernetes ORM 拡張機能では、計算式のオペランドとして関数呼び出しをサポートしていないため、日時関数を算術演算子と組み合わせることはできません。詳細については、「クエリの指定」ガイドの「計算式の使用」セクションを参照してください。

サンプルデータ

このガイドの例では、AtlasサンプルデータセットのMovie sample_mflix.moviesコレクションを表すエンティティを使用します。Movie エンティティには、次の定義があります。

import com.mongodb.hibernate.annotations.ObjectIdGenerator;
import org.bson.types.ObjectId;
import java.time.Instant;
import java.util.List;
import jakarta.persistence.Embedded;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.Id;
import jakarta.persistence.OneToMany;
import jakarta.persistence.Table;
@Entity
@Table(name = "movies")
public class Movie {
   @Id
   @ObjectIdGenerator
   private ObjectId id;
   private String title;
   private String plot;
   private int year;
   private List<String> cast;
   private List<String> directors;
   private Instant released;
   @Embedded
   private Awards awards;
   @OneToMany(mappedBy = "movie", fetch = FetchType.LAZY)
   private List<Comment> comments;
   public Movie(String title, String plot, int year, List<String> cast, List<String> directors, Instant released, Awards awards) {
      this.title = title;
      this.plot = plot;
      this.year = year;
      this.cast = cast;
      this.directors = directors;
      this.released = released;
      this.awards = awards;
   }
   public Movie() {
   }
   public ObjectId getId() {
      return id;
   }
   public String getTitle() {
      return title;
   }
   public void setTitle(String title) {
      this.title = title;
   }
   public String getPlot() {
      return plot;
   }
   public void setPlot(String plot) {
      this.plot = plot;
   }
   public int getYear() {
      return year;
   }
   public void setYear(int year) {
      this.year = year;
   }
   public List<String> getCast() {
      return cast;
   }
   public void setCast(List<String> cast) {
      this.cast = cast;
   }
   public List<String> getDirectors() {
      return directors;
   }
   public void setDirectors(List<String> directors) {
      this.directors = directors;
   }
   public Awards getAwards() {
      return awards;
   }
   public void setAwards(Awards awards) {
      this.awards = awards;
   }
   public Instant getReleased() {
      return released;
   }
   public void setReleased(Instant released) {
      this.released = released;
   }
   public List<Comment> getComments() {
      return comments;
   }
   public void setComments(List<Comment> comments) {
      this.comments = comments;
   }
}

Hibernetes ORM 用のMongoDB拡張機能を使用してこのMongoDBサンプルコレクションと交流するJavaアプリケーションを作成する方法については、Get Started チュートリアルを参照してください。

このガイドの例では、Instant 値を保存する Movie エンティティの releasedフィールドを使用します。

日時フィールドの抽出

extract() 関数を使用すると、年、月、日などの特定の部分の日時値を返すことができます。

extract(field from x) 関数は、日時値の単一のフィールドを返します。 Hibernetes ORM 拡張機能は field の次の値をサポートしています。

フィールド	MongoDB の変換
`year`	`$year`
`quarter`	`$month` を `3` で除算し、切り上げて計算
`month`	`$month`
`week`	`$isoWeek`は、 ISO-8601 週番号を返します
`week of year`	日曜日ベースの週番号として `$dayOfYear` と `$dayOfWeek` から計算
`week of month`	日曜日ベースの週番号として `$dayOfMonth` と `$dayOfWeek` から計算
`day`, `day of month`	`$dayOfMonth`
`day of week`	`$dayOfWeek`
`day of year`	`$dayOfYear`
`hour`	`$hour`
`minute`	`$minute`
`second`	`$second` と `$millisecond` から小数秒として計算
`nanosecond`	`$second` と `$millisecond` から計算
`epoch`	UNIXエポックからの整数秒数として計算

次の例では、 sample_mflix.moviesコレクション内の各 "Hairspray" 映画のタイトルと、その映画が公開された年を返します。

var extractResult = session.createQuery(
                "select title, extract(year from released) as releaseYear from Movie where title = :title",
                Object[].class)
        .setParameter("title", "Hairspray")
        .getResultList();
for (var row : extractResult) {
    System.out.println("Title: " + row[0] + ", Release Year: " + row[1]);
}

Title: Hairspray, Release Year: 1988
Title: Hairspray, Release Year: 2007

var extractResult = entityManager.createQuery(
                "select m.title, extract(year from m.released) as releaseYear from Movie m where m.title = :title",
                Object[].class)
        .setParameter("title", "Hairspray")
        .getResultList();
for (var row : extractResult) {
    System.out.println("Title: " + row[0] + ", Release Year: " + row[1]);
}

Title: Hairspray, Release Year: 1988
Title: Hairspray, Release Year: 2007

Hibernetes ORM 拡張機能は、前述のクエリを次の $project ステージに変換します。ここで、America/New_York はJVMのデフォルトのタイムゾーンです。

{
  "$project": {
    "title": true,
    "releaseYear": {
      "$year": {
        "date": "$released",
        "timezone": { "$literal": "America/New_York" }
      }
    },
    "_id": 0
  }
}

重要

曜日番号付け

day of weekフィールドはMongoDB $dayOfWeek 値を返します。これは日曜日の 1 から土曜日の 7 までの日数です。これはJava DayOfWeek列挙とは異なります。これは月曜日、1 から日曜日の 7 までの日数です。

Hibernetes ORM 拡張機能は、date、time、offset、timezone_hour、timezone_minute フィールドをサポートしていません。サポートされていないフィールドを抽出するクエリでは、FeatureNotSupportedException がスローされます。

日時を string として形式する

format(x as pattern)関数は日時値を string としてレンダリングします。 Hibernetes ORM 拡張機能はMongoDB $dateToString 演算子への呼び出しを変換し、各パターンコードを同等のMongoDB形式指定子にマッピングします。また、関数をとして呼び出して、format(x, pattern) MongoDB形式指定子を直接渡すこともできます。

Hibernetes ORM 拡張機能は次のパターンコードをサポートしています。

パターンコード	説明	MongoDB指定子
`yyyy`	4 桁の年	`%Y`
`YYYY`	4 桁の ISO-8601 週ベースの年	`%G`
`MM`	2 桁の月	`%m`
`MMM`	省略表記の月名	`%b`
`MMMM`	正式な月名	`%B`
`ww`	2 桁の ISO-8601 週番号	`%V`
`dd`	日付（2桁）	`%d`
`DDD`	日付	`%j`
`HH`	24 時間制で 2 桁の時間	`%H`
`mm`	2桁の分	`%M`
`ss`	2 桁の秒	`%S`
`SSS`	3桁のミリ秒	`%L`
`Z`, `ZZ`, `ZZZ`, `xx`	UTC オフセット	`%z`

MongoDB は、 USロケールで月名と日付名を返します。一重引用符で囲む文字は、パターンコードとして解釈されることなく、出力に渡されます。

次の例では、各 "Hairspray" 映画のタイトルとその公開日を yyyy-MM-dd string として返します。

var formatResult = session.createQuery(
                "select title, format(released as 'yyyy-MM-dd') as releaseDate from Movie where title = :title",
                Object[].class)
        .setParameter("title", "Hairspray")
        .getResultList();
for (var row : formatResult) {
    System.out.println("Title: " + row[0] + ", Release Date: " + row[1]);
}

Title: Hairspray, Release Date: 1988-02-25
Title: Hairspray, Release Date: 2007-07-19

代わりにMongoDB形式指定子を使用する場合は、関数を format(released, '%Y-%m-%d') として呼び出します。

var formatResult = entityManager.createQuery(
                "select m.title, format(m.released as 'yyyy-MM-dd') as releaseDate from Movie m where m.title = :title",
                Object[].class)
        .setParameter("title", "Hairspray")
        .getResultList();
for (var row : formatResult) {
    System.out.println("Title: " + row[0] + ", Release Date: " + row[1]);
}

Title: Hairspray, Release Date: 1988-02-25
Title: Hairspray, Release Date: 2007-07-19

代わりにMongoDB形式指定子を使用する場合は、関数を format(m.released, '%Y-%m-%d') として呼び出します。

Hibernetes ORM 拡張機能は、前述のクエリを次の $project ステージに変換します。

{
  "$project": {
    "title": true,
    "releaseDate": {
      "$dateToString": {
        "date": "$released",
        "format": { "$literal": "%Y-%m-%d" },
        "timezone": { "$literal": "America/New_York" }
      }
    },
    "_id": 0
  }
}

上記表の外部のパターンコードを使用するクエリでは FeatureNotSupportedException がスローされます。これには、y、M、d、H、h、m、s、a などの単一文字と変数幅のコードが含まれます。MongoDBには同等のコードがないためです。指定します。 3 文字を超えるタイムゾーンコードが繰り返される場合（ZZZZZZZ など）はあいまいなため、例外もスローされます。

詳細情報

クエリフィルターの作成とクエリステートメントでの演算子の使用の詳細については、「クエリの指定」ガイドを参照してください。

HQL と JQL を使用してクエリを実行する方法の詳細については、非表示の ORM ドキュメントの「非表示のクエリ言語へのガイド」を参照してください。

戻る

クエリを指定する

コレクション間でエンティティを結合