Salesforce SOQLクエリのTODAYとは？概要や扱い方をご紹介

SalesforceのSOQLとは？

SalesforceのSOQLとは、Salesforceオブジェクトのクエリ言語です。 SOQLは「Salesforce Object Query Language」の略で、Salesforceのデータベースに対してクエリを発行できます。SOQLは標準のSQL言語に似た構文ですが、Lightning Platform用にカスタマイズされています。 SOQLクエリを実行するには、開発者コンソールのクエリエディタに記述する方法と、Apexコードに記述する方法があります。

クエリエディタにSOQLを記述する方法

開発者コンソールのクエリエディタコンソールにSOQLクエリを記述すれば実行できます。 クエリエディタコンソールにSOQLクエリを記述すれば、簡単にすばやくデータベースにアクセスできます。例えば、SOQLクエリをApexコードに追加する前のテストとして、試しに実行結果を確認する場合などに使用できます。

サンプルコード

基本的なSOQLクエリの構文について説明します。 以下は、基本的なSOQLクエリの構文です。WHERE句は省略可能です。

SELECT fields FROM ObjectName [WHERE Condition]

以下のSOQLクエリは、全取引先から各取引先の名前と電話番号を取得しています。

SELECT Name,Phone FROM Account

詳しく説明すると、「SELECT Name,Phone」は、取得する項目を指定しています。取得する項目が複数あるのでSELECTキーワードの後に「,」で区切っています。仮に取得する項目が1つの場合は「,」区切りは不要です。 次に「FROM Account」は、取得するカスタムオブジェクトを指定しています。今回の例ではAccountです。

ApexコードにSOQLを記述する方法

ApexコードにSOQLクエリを記述すれば実行できます。 Apexはデータベースに保存されているSalesforceレコードに直接アクセスすることが可能なので、SOQLクエリをApexコードに記述すれば、実行結果を簡単に取得できます。Apexに記述したSOQLをインラインSOQLと呼びます。

サンプルコード

ApexコードにSOQLクエリを記述するサンプルコードを説明します。 SOQLクエリをApexコードに記述する際は、SOQLステートメントを「[」、「]」で囲み、戻り値をsObject配列に代入します。 以下の例では、名前と電話番号の2つを持つすべての取引先レコードを取得してAccount sObjectの配列を戻り値にしています。

Account[] accts = [SELECT Name,Phone FROM Account];

「*」の指定について

SOQLでは、「*」を指定することはできません。 他のSQL言語では「*」を指定すれば、すべての項目を取得できますが、SOQLでは必ず取得する項目を明示的に指定する必要があるため、「*」を使用できません。 仮に、SELECT句で指定していない項目にアクセスすると、エラーになります。

IDの指定について

SOQLでは、ID項目をクエリに指定する必要はありません。 Apexコードに記述したSOQLクエリでは、指定されたかどうかに関係なく、常にID項目が返されます。例えば、「SELECT Id,Phone FROM Account」と「SELECT Phone FROM Account」は同等の命令になります。 ただし、少なくとも1つの項目は必要なので、ID項目のみを取得する場合は、「SELECT Id FROM Account」のようにID項目を指定する必要があります。

Salesforce SOQLクエリのTODAYとは？

Salesforce SOQLクエリのTODAYとは、今日の日付を取得する命令です。 Salesforce SOQLクエリでは、特定日付や日付リテラルを指定できます。日付リテラルとは、先月、今週、来年などの時間範囲を表す固定の値です。日付リテラルの1つにTODAYがあります。 TODAYの範囲は、「本日の00:00:00」から「24時間後」までを指します。 例えば、TODAYを使用した以下のSOQLでは、本日作成したレコードのIDを取得しています。

SELECT Id FROM Account WHERE CreatedDate = TODAY

タイムゾーンについて

SalesforceのSOQLクエリで扱うタイムゾーンはUTC値なので注意が必要です。 UTC値とは協定世界時のことです。協定世界時は、イギリスのグリニッジ天文台を基準とした世界中で使われる標準時のことです。システムの時間が日本標準時であれば、9時間ずれた値で表示されます。 SOQLクエリのTODAYなどで取得したUTC値を扱う場合は、そのままでは使用できないので、タイムゾーンをシステムの時間（日本なら日本標準時）に変換する必要があります。

タイムゾーンの変換

SalesforceのSOQLクエリが返すUTC値（協定世界時）のタイムゾーンは、日付関数で変換して使用します。 SOQLクエリのTODAYなどで取得したUTC値のタイムゾーンを、システムのタイムゾーンに変換するには、日付関数の「convertTimezone()」を使用します。 例えば、次のように変換します。

SELECT HOUR_IN_DAY(convertTimezone(CreatedDate)), SUM(Amount)
FROM Opportunity
GROUP BY HOUR_IN_DAY(convertTimezone(CreatedDate))

ただし、次のように、「convertTimezone()」単独での使用では機能しません。

SELECT convertTimezone(CreatedDate)
FROM Opportunity

日付のデータ形式について

日付を扱う場合、データ形式によって注意が必要です。 日付を文字列型に変換する場合、「yyy-MM-dd」形式にする必要があります。文字列型ではなく、Date型なら「String.valueOf(myDate)」を指定すれば自動的にDate型に変換してくれます。 例えば、「yyyy/MM/dd」のように「/」区切りの文字列を日付として扱いたい場合は、「Date.parse」メソッドを使用して、日付型に変換した後に「yyyy-MM-dd」形式の文字列に変換する必要があります。

String strDate = '2011/12/31';
Date myDate = Date.parse(strDate);
... WHERE Close Date <= ' + String.valueOf(myDate)

日付の指定方法

日付を文字列で指定する場合、シングルクォーテーションで囲まないでください。 以下が正しい例です。

WHERE Close Date <= ' + String.valueOf(myDate)

間違って、以下のようにシングルクォーテーションで囲まないでください。

WHERE Close Date <= \'' + String.valueOf(myDate) + '\''

こうしてしまうと、次のようなエラーメッセージが出てしまいます。 「value of filter criterion for field ‘[項目]’ must be of type date and should not be enclosed in quotes」

Salesforce SOQLクエリのTODAYを活用しよう！

今回は、SalesforceのSOQLクエリとSOQLクエリのTODAYについて、説明しました。 また、SOQLクエリのTODAYの戻り値である日付のタイムゾーンやデータ形式についても説明しました。TODAYの戻り値は、システムの時間ではなく、協定世界時のUTC値であるため、使用する場合は日付関数で変換する必要があるので、注意が必要です。 また、文字列で扱う場合も「yyyy-MM-dd」形式にする必要がある点も注意が必要です。 今回説明したことを理解し、ぜひこの機会にSOQLクエリのTODAYを活用できるようにしておきましょう。]]>