位置情報に基づく SOQL クエリ

地理位置情報カスタム項目種別を使用すると、位置情報の値を保存する項目を作成できます。地理位置情報項目では、緯度と経度に基づいて場所を識別します。Salesforce オブジェクトの標準住所にも地理位置情報項目が含まれており、(値が入力されていれば) 同じように使用できます。ただし、いくつかの制限があります。どちらの種別でも、場所を比較したり照合したりできます。たとえば、最も近い 10 件の取引先を見つけることができます。

詳細と考慮事項については、『Salesforce オブジェクトリファレンス』の「複合項目」を参照してください。

位置情報に基づく SOQL クエリに対応している項目種別

SOQL では、GEOLOCATION 関数を使用して、緯度と経度に単純な数値を指定できます。これらの値は、標準数値項目、ユーザー入力、計算値などから取得できます。地理位置情報項目の個々のコンポーネントから取得することもできます。この項目では、緯度と経度の両方を 1 つの論理項目に格納しています。地理コードサービスによって標準住所の地理位置情報項目が入力される場合は、住所から直接、緯度と経度の値を使用することもできます。

SOAP API および REST API を使用して作成された SOQL では、地理位置情報コンポーネントを含む住所項目など、地理位置情報項目を、SOQL ステートメント内で直接使用することもできます。これにより多くの場合、SOQL ステートメントが簡素化されます。複合項目は、SOAP API および REST API を使用して作成された SOQL クエリのみで使用できます。

SELECT 句

1SELECT Name, Location__latitude__s, Location__longitude__s 
2FROM Warehouse__c

1SELECT Name, Location__c 
2FROM Warehouse__c

1{
2  "totalSize" : 10,
3  "done" : true,
4  "records" : [ {
5    "attributes" : {
6      "type" : "Warehouse__c",
7      "url" : "/services/data/v30.0/sobjects/Warehouse__c/a06D00000017O4nIAE"
8    },
9    "Name" : "Ferry Building Depot",
10    "Location__c" : {
11      "latitude" : 37.79302,
12      "longitude" : -122.394507
13    }
14  }, {
15    "attributes" : {
16      "type" : "Warehouse__c",
17      "url" : "/services/data/v30.0/sobjects/Warehouse__c/a06D00000017O4oIAE"
18    },
19    "Name" : "Aloha Warehouse",
20    "Location__c" : {
21      "latitude" : 37.786108,
22      "longitude" : -122.430152
23    }
24  }, 
25  ...
26  ]
27}

WHERE 句

1SELECT Name, Location__c 
2FROM Warehouse__c 
3WHERE DISTANCE(Location__c, GEOLOCATION(37.775,-122.418), 'mi') < 20

ORDER BY 句

1SELECT Name, StreetAddress__c 
2FROM Warehouse__c 
3WHERE DISTANCE(Location__c, GEOLOCATION(37.775,-122.418), 'mi') < 20 
4ORDER BY DISTANCE(Location__c, GEOLOCATION(37.775,-122.418), 'mi')
5LIMIT 10

SOQL が Null の位置情報の値を処理する方法

地理位置情報項目は、地球上のある地点を示すために緯度と経度の値を組み合わせる複合項目です。null 値は、緯度と経度の両方が null の場合にのみ有効です。

地理位置情報項目値が無効なレコードでは、緯度と経度の両方の値が、SOQL の WHERE DISTANCE() と ORDER BY の句で使用された場合に Null として処理されます。緯度または経度のどちらかが Null である地理位置情報項目を持つレコードは、項目が設定されていないものとして処理されます。

1SELECT Name, Location__c 
2FROM Warehouse__c 
3LIMIT 5

1SELECT Name, Location__latitude__s, Location__longitude__s 
2FROM Warehouse__c 
3LIMIT 5

DISTANCE の計算に使用する数式項目を作成するときは、[空白項目の処理] セクションの [空白項目を空白として処理] を選択します。[空白項目を 0 として処理] を選択した場合、地理位置情報項目に Null 値があると、赤道がグリニッジ子午線と交差する位置 (0°, 0°) を基準に距離が計算されます。レコード詳細ページでは、[空白項目を 0 として処理] に設定されている DISTANCE 数式項目に Null 値の地理位置情報の値があると、数式項目が空白になります。

SOQL による距離の計算と比較の方法

DISTANCE 関数は、半正矢 (大円) の距離計算を 0.0002% 以内に近似します。この数式では、地球は完全な球体だと仮定していますが、地球は実際には楕円形、つまり不規則な球体です。この仮定の誤差は、赤道を横断するときに最大 0.55% になる可能性があります。ただし緯度と進行方向にもよりますが、通常は 0.3% 以下です。

顧客の現在の場所に最も近い 10 件の店舗を計算する場合は、DISTANCE 関数を使用しても問題ありません。ただし、この関数に基づいて、サンフランシスコからシドニーまでのフライトの飛行機に燃料を補給するのはやめましょう。

1WHERE ( DISTANCE(Location__c, testLocation) < 0.05 )

距離がほぼ同じ場合は小さな誤差ですみますが、誤差によって、期待した場所が位置情報クエリの結果に含まれたり、含まれなかったりすることがあります。アプリケーションで正確な距離の計算と比較を行う必要がある場合は、自身で計算することをお勧めします。

位置情報に基づく SOQL クエリの考慮事項

位置情報に基づくクエリは、Apex の SOQL と、SOAP API および REST API でサポートされています。次の考慮事項に留意します。

• DISTANCE と GEOLOCATION は、SOQL の WHERE 句および ORDER BY 句ではサポートされますが、GROUP BY 句ではサポートされません。DISTANCE は SELECT 句でサポートされます。
• DISTANCE は、論理演算子 > および < のみをサポートし、指定された半径内 (<) または外 (>) の値を返します。
• SOQL クエリで GEOLOCATION 関数を使用する場合、地理位置情報項目を緯度および経度座標よりも前に入力する必要があります。たとえば、DISTANCE(warehouse_location__c, GEOLOCATION(37.775,-122.418), 'km') は機能しますが、DISTANCE(GEOLOCATION(37.775,-122.418), warehouse_location__c, 'km') は機能しません。
• Apex バインド変数は、DISTANCE 関数の単位パラメーターではサポートされません。次のクエリは機能しません。

  1String units = 'mi';
  2List<Account> accountList = 
  3    [SELECT ID, Name, BillingLatitude, BillingLongitude 
  4     FROM Account 
  5     WHERE DISTANCE(My_Location_Field__c, GEOLOCATION(10,10), :units) < 10];

詳細は、『Salesforce オブジェクトリファレンス』に記載されている「複合項目の考慮事項と制限」を参照してください。