|
|
型目次
MongoDB では、PHP のすべての基本データ型や複合型 (配列、連想配列
そしてオブジェクト) を保存したり問い合わせたりすることができます。
それ以外にも、MongoDB PHP ドライバには (正規表現や
日付、その他さまざまな用途に特化した) クラスが用意されています。
Boolean および null
true、false および null はそのままの型で使えます。
数値
MongoDB では数値と文字列は区別されます。"123" は 123 とマッチしません。
したがって、数値のソートやマッチングを正しく行うには、数値として保存しなければなりません。
<?php
$doc = array("a" => 123, "b" => "123");
$collection->insert($doc);
$doc->find(array("a" => 123)); // マッチします
$doc->find(array("a" => "123")); // マッチしません
$doc->find(array("a" => 123.0)); // マッチします
$doc->find(array("b" => 123)); // マッチしません
$doc->find(array("b" => "123")); // マッチします
?>
上に示したように、浮動小数点数と整数の比較やマッチングは期待通りにできます。
大きな数値
デフォルトでは、32 ビットシステム上では数値をデータベースに送信するときには 32 ビット整数型となります。
64 ビットシステム上では数値をデータベースに送信するときには 64 ビット整数型となります。
過去との互換性を保つため、64 ビット整数型をデシリアライズするとすべてのシステムで浮動小数点数となります。
浮動小数点数には誤差があります。正確な値が必要なら
php.ini の設定をしましょう。
32 ビットシステム上では、mongo.long_as_object
が設定されていると 64 ビット整数値が MongoInt64 オブジェクトとして返されます。
整数値は、value フィールドに完全な精度で (文字列として) 格納されます。
MongoInt64 を使えば、64 ビット整数値を 32 ビットマシン上に保存することもできます。
64 ビットシステム上では、mongo.long_as_object
あるいは mongo.native_long を設定することができます。
mongo.native_long は、64 ビット整数値を
"通常の" PHP の整数型で返します。MongoInt32 を使えば、
32 ビット整数値を 64 ビットマシン上に保存することができます。
mongo.long_as_object や
mongo.native_long の挙動は、使おうとする内容にあわせて設定するべきです。
たとえデフォルトの挙動であっても、明示的に設定しておくことが大切です
(将来もしデフォルトの設定が変わっても、その影響を受けずにすみます)。
php.ini のオプション、
MongoInt32、そして MongoInt64
も参照ください。
文字列
文字列は UTF-8 でなければなりません。非 UTF-8 文字列は、UTF-8
に変換してからデータベースに送信するか、あるいはバイナリデータとして保存しなければなりません。
正規表現を使った文字列のマッチングができます。正規表現には
MongoRegex クラスを使います。
バイナリデータ
非 UTF-8 文字列や画像その他のバイナリデータをデータベースに送信するときには
MongoBinData 型を使わなければなりません。
日付
日付を作成するには MongoDate クラスを使います。
ここにはエポックからの経過ミリ秒数が格納されます。
MongoTimestamp は日付やタイムスタンプを保存するためのものではなく、
MongoDB の内部で使うものです。レプリカやシャーディングの内部構造を扱うツールを書いているのでない限り、
MongoTimestamp ではなく
MongoDate を使うべきです。
一意な Id
ドライバは、ユーザーが明示的に指定しない限り、自動的に _id
フィールドを作成してからドキュメントを追加します。このフィールドは
MongoId (いわゆる "オブジェクト ID")
のインスタンスです。
ID は 12 バイトで、このような構造です。
-
タイムスタンプ 4 バイト
別の時刻に追加されたレコードが同じ id になることはありません。
-
マシン id 3 バイト
別のマシンから追加されたレコードが同じ id になることはありません。
-
スレッド id 2 バイト
同じマシン上の別のスレッドから追加されたレコードが同じ id になることはありません。
-
増分 3 バイト
id が新たに作られるたびにグローバルなカウンタがひとつ増加します。
次の id を作るときに、この値を使います。
従って、同一マシン上の単一のプロセスで 1 秒間に 256^3 件 (1600万件以上)
のレコードを追加 (増分領域を使い切る) しようとしない限り、
同じ id になることはありません。
JavaScript
MongoDB には JavaScript エンジンが組み込まれているので、JavaScript
をクエリに ($where 句で) 組み込んで直接データベースに送信して実行し、
集約することができます。
セキュリティ上、MongoCode の scope
フィールドを使って PHP の変数を JavaScript に渡します。外部の値を使わないコードの場合は
MongoCode を使っても単なる文字列を使ってもかまいません。
JavaScript をデータベースに送信することに関する詳細な情報は
セキュリティの節
を参照ください。
配列およびオブジェクト
配列やオブジェクトもデータベースに格納することができます。
数値添字の配列は配列として、
それ以外のものはすべてオブジェクトとして格納されます。
<?php
// $scores は配列として格納されます
$scores = array(98, 100, 73, 85);
$collection->insert(array("scores" => $scores));
// $scores はオブジェクトとして格納されます
$scores = array("quiz1" => 98, "midterm" => 100, "quiz2" => 73, "final" => 85);
$collection->insert(array("scores" => $scores));
?>
データベースのシェルからこれらのオブジェクトを問い合わせると、このようになります。
> db.students.find()
{ "_id" : ObjectId("4b06beada9ad6390dab17c43"), "scores" : [ 98, 100, 73, 85 ] }
{ "_id" : ObjectId("4b06bebea9ad6390dab17c44"), "scores" : { "quiz1" : 98, "midterm" : 100, "quiz2" : 73, "final" : 85 } }
任意の PHP オブジェクトもデータベースに格納することができます
(返されるときは連想配列となります)。
フィールドは キー/値 のペアに使います。
たとえば、blogへの投稿を表す次のようなオブジェクトを考えましょう。
<?php
// blog投稿クラス
class Post {
var $author;
var $content;
var $comments = array();
var $date;
public function __construct($author, $content) {
$this->author = $author;
$this->content = $content;
$this->date = new MongoDate();
}
public function setTitle($title) {
$this->title = $title;
}
}
// 単純なblog投稿を作り、データベースに追加します
$post1 = new Post("Adam", "This is a blog post");
$blog->insert($post1);
// "author" フィールドの型には何も制約がないので、
// オブジェクトをネストさせることができます
$author = array("name" => "Fred", "karma" => 42);
$post2 = new Post($author, "This is another blog post.");
// タイトルを設定して、別のフィールドを追加することができます
$post2->setTitle("Second Post");
$blog->insert($post2);
?>
データベースのシェルからは、次のように見えます。
> db.blog.find()
{ "_id" : ObjectId("4b06c263edb87a281e09dad8"), "author" : "Adam", "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:22:59 GMT-0500 (EST)" }
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "author" : { "name" : "Fred", "karma" : 42 }, "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:23:30 GMT-0500 (EST)", "title" : "Second Post" }
このドライバは、配列やオブジェクトの循環参照を検出することができません。
たとえば、これは致命的なエラーとなります。
<?php
$collection->insert($GLOBALS);
?>
Fatal error: Nesting level too deep - recursive dependency?
再帰構造になる可能性のあるドキュメントを追加しなければならない場合は、
ドライバに渡す前に自分でチェックしておかなければなりません。
The MongoId class
警告
このクラスを定義している拡張モジュールは非推奨です。
かわりに MongoDB 拡張モジュールを使うべきです。
このクラスの代替として、以下が使えます。
はじめに
A unique identifier created for database objects. If an object is inserted
into the database without an _id field, an _id field will be added to it
with a MongoId instance as its value. If the data
has a naturally occuring unique field (e.g. username or timestamp) it is
fine to use this as the _id field instead, and it will not be replaced with
a MongoId.
Instances of the MongoId class fulfill the role that
autoincrementing does in a relational database: to provide a unique key if
the data does not naturally have one. Autoincrementing does not work well
with a sharded database, as it is difficult to determine the next number in
the sequence. This class fulfills the constraints of quickly generating a
value that is unique across shards.
Each MongoId is 12 bytes (making its string form 24 hexadecimal characters).
The first four bytes are a timestamp, the next three are a hash of the
client machine's hostname, the next two are the two least significant bytes
of the process id running the script, and the last three bytes are an
incrementing value.
MongoIds are serializable/unserializable. Their
serialized form is similar to their string form:
C:7:"MongoId":24:{4af9f23d8ead0e1d32000000}
クラス概要
MongoId
class MongoId
{
public
string
$$id
= null
;
public __construct
([ stringMongoId $id = null
] )
public static string getHostname
( void
)
public int getInc
( void
)
public int getPID
( void
)
public int getTimestamp
( void
)
public static bool isValid
( mixed $value
)
public static MongoId __set_state
( array $props
)
public string __toString
( void
)
}
Fields
- $id
-
This field contains the string representation of this object.
注意:
The property name begins with a $ character. It may
be accessed using
complex variable
parsed syntax (e.g. $mongoId->{'$id'}).
MongoCode クラス
警告
このクラスを定義している拡張モジュールは非推奨です。
かわりに MongoDB 拡張モジュールを使うべきです。
このクラスの代替として、以下が使えます。
はじめに
データベース用の JavaScript コードを表します。
MongoCode オブジェクトはふたつの部分からなります。
コード文字列、そしてオプションのスコープです。
コード文字列は JavaScript として正しい形式でなければなりません。
スコープは、変数名とその値のペアからなる連想配列です。
クラス概要
MongoCode
class MongoCode
{
public __construct
( string $code
[, array $scope = array()
] )
public string __toString
( void
)
}
MongoDate クラス
警告
このクラスを定義している拡張モジュールは非推奨です。
かわりに MongoDB 拡張モジュールを使うべきです。
このクラスの代替として、以下が使えます。
はじめに
データベースの日付オブジェクトを表します。日付をデータベースに保存したり、
日付を問い合わせたりするときにはこのクラスを使わなければなりません。
次のように使います。
例1 MongoDate による日付の保存
<?php
// 日付をデータベースに保存します
$collection->save(array("ts" => new MongoDate()));
$start = new MongoDate(strtotime("2010-01-15 00:00:00"));
$end = new MongoDate(strtotime("2010-01-30 00:00:00"));
// 2010/1/15 から 2010/1/30 までの日付を検索します
$collection->find(array("ts" => array('$gt' => $start, '$lte' => $end)));
?>
MongoDB は、日付データをエポックからの経過ミリ秒数で格納します。
つまり、日付にはタイムゾーンの情報が
含まれないということです。
タイムゾーンが必要なら、別のフィールドを用意する必要があります。
また、データベースとの間でドキュメントをやりとりすると、
ミリ秒より細かい単位の情報は失われてしまいます。
クラス概要
MongoDate
class MongoDate
{
public
int
$sec
;
public
int
$usec
;
public __construct
([ int $sec = time()
[, int $usec = 0
]] )
public DateTime toDateTime
( void
)
public string __toString
( void
)
}
MongoRegex クラス
警告
このクラスを定義している拡張モジュールは非推奨です。
かわりに MongoDB 拡張モジュールを使うべきです。
このクラスの代替として、以下が使えます。
はじめに
このクラスを使うと正規表現を作ることができます。
典型的な使い道は、データベースへの問い合わせでマッチする文字列を検索することです。
それ以外に、正規表現をデータベースに格納したりデータベースから取得したりすることもできます。
正規表現は、四つの部分で構成されています。最初は区切り文字の /、
そしてその後にパターンが続き、さらにもう一度区切り文字の /、
そして最後がフラグを表す文字です。
Mongo は 6 つの正規表現フラグに対応しています。
-
i: 大文字小文字を区別しない
-
m: 複数行
-
x: コメントを含めることができる
-
l: ロケール
-
s: "." が、改行を含むすべてにマッチする
-
u: unicode にマッチする
クラス概要
MongoRegex
class MongoRegex
{
public
string
$regex
;
public
string
$flags
;
public __construct
( string $regex
)
public string __toString
( void
)
}
MongoBinData クラス
警告
このクラスを定義している拡張モジュールは非推奨です。
かわりに MongoDB 拡張モジュールを使うべきです。
このクラスの代替として、以下が使えます。
はじめに
データベースからのバイナリデータを保存したり取得したりする際に使用するオブジェクトです。
データベースに挿入できるひとつのオブジェクトの最大サイズは 16MB です。
それよりも大きいデータ (動画や音楽、キッシンジャーの自伝など) の場合は
MongoGridFS を使います。16MB より小さなデータの場合は、
MongoBinData を使ってドキュメントに埋め込むほうが簡単でしょう。
たとえば画像をドキュメントに埋め込むには、このようにします。
<?php
$profile = array(
"username" => "foobity",
"pic" => new MongoBinData(file_get_contents("gravatar.jpg"), MongoBinData::GENERIC),
);
$users->save($profile);
?>
このクラスには type フィールドがありますが、
現時点ではこのフィールドはドライバやデータベースに対して何の効果も及ぼしません。
7 種類の型が定義済み (以下のクラス定数を参照ください) です。
過去のバージョンとの互換性のため、デフォルトは
MongoBinData::BYTE_ARRAY
となっていますが、将来のバージョンでは
MongoBinData::GENERIC に変わるかもしれません。
MongoBinData::__construct できちんと型を定義するようにしましょう。
クラス概要
MongoBinData
class MongoBinData
{
const
int
MongoBinData::GENERIC
= 0
;
const
int
MongoBinData::FUNC
= 1
;
const
int
MongoBinData::BYTE_ARRAY
= 2
;
const
int
MongoBinData::UUID
= 3
;
const
int
MongoBinData::UUID_RFC4122
= 4
;
const
int
MongoBinData::MD5
= 5
;
const
int
MongoBinData::CUSTOM
= 128
;
public
string
$bin
;
public
int
$type
= 2
;
public __construct
( string $data
[, int $type = 0
] )
public string __toString
( void
)
}
定義済み定数
バイナリデータ型
MongoBinData::GENERIC-
汎用的なバイナリデータ。
MongoBinData::FUNC-
関数。
MongoBinData::BYTE_ARRAY-
汎用的なバイナリデータ (非推奨。かわりに
MongoBinData::GENERIC を使いましょう)。
MongoBinData::UUID-
全体で一意な識別子 (非推奨。かわりに
MongoBinData::UUID_RFC4122 を使いましょう)。
MongoBinData::UUID_RFC4122-
全体で一意な識別子
(» RFC 4122 準拠)。
MongoBinData::MD5-
MD5。
MongoBinData::CUSTOM-
ユーザー定義型。
MongoInt32 クラス
警告
このクラスを定義している拡張モジュールは非推奨です。
かわりに MongoDB 拡張モジュールを使うべきです。
このクラスの代替は、新しい拡張モジュールには存在しません。
新しい拡張モジュールでは、整数の値に応じてデータベースの型を適切に選びます。
はじめに
このクラスを使うと、32 ビット整数値を 64 ビットシステム上のデータベースに保存することができます。
クラス概要
MongoInt32
class MongoInt32
{
public
string
$value
;
public __construct
( string $value
)
public string __toString
( void
)
}
フィールド
- value
-
32 ビット数値を文字列で表した値。たとえば 123 の value
は "123" となります。
MongoInt64 クラス
警告
このクラスを定義している拡張モジュールは非推奨です。
かわりに MongoDB 拡張モジュールを使うべきです。
このクラスの代替は、新しい拡張モジュールには存在しません。
新しい拡張モジュールでは、整数の値に応じてデータベースの型を適切に選びます。
はじめに
このクラスを使うと、64 ビット整数値を 32 ビットシステム上のデータベースに保存することができます。
クラス概要
MongoInt64
class MongoInt64
{
public
string
$value
;
public __construct
( string $value
)
public string __toString
( void
)
}
フィールド
- value
-
64 ビット数値を文字列で表した値。たとえば 123 の value
は "123" となります。
MongoDBRef クラス
警告
このクラスを定義している拡張モジュールは非推奨です。
かわりに MongoDB 拡張モジュールを使うべきです。
このクラスの代替は、新しい拡張モジュールには存在しません。
The concept of database references, and hence this class, has been
deprecated in the database.
はじめに
このクラスを使用して、別々のコレクション内にあるオブジェクト間の軽量なリンクを作成します。
動機: 別のコレクションにあるドキュメントを参照する必要が出てきたとしましょう。
いちばん簡単な方法は、現在のドキュメントにフィールドを作ることです。
たとえば、"people" コレクションと "addresses" コレクションがあるときに
人物のドキュメントと住所のドキュメントをリンクさせたいことがあるでしょう。
例1 ドキュメントのリンク
<?php
$people = $db->people;
$addresses = $db->addresses;
$myAddress = array("line 1" => "123 Main Street",
"line 2" => null,
"city" => "Springfield",
"state" => "Vermont",
"country" => "USA");
// 住所を保存します
$addresses->insert($myAddress);
// その住所を参照する人物を保存します
$me = array("name" => "Fred", "address" => $myAddress['_id']);
$people->insert($me);
?>
そうすれば、誰かの住所を知りたくなったときには、
"people" コレクションに保存した MongoId
を使って "addresses" コレクションを検索することができます。
もう少し一般化してみましょう。参照したいドキュメントがどのコレクション
(あるいはどのデータベース) にあるかわからない場合です。こんな場合に
MongoDBRef が使えます。
これは共通のフォーマットであり、すべてのドライバやデータベースが理解できるからです。
各個人が「好きなもの」リストを持っており、それはいろいろなコレクション
("hobbies", "sports", "books" など) にあるとしましょう。
MongoDBRef を使えば、それぞれがどのコレクションからのものかを管理できます。
例2 MongoDBRef リンクの作成
<?php
$people = $db->selectCollection("people");
// 鉄道模型は "hobbies" コレクションにあります
$trainRef = MongoDBRef::create("hobbies", $modelTrains['_id']);
// サッカーは "sports" コレクションにあります
$soccerRef = MongoDBRef::create("sports", $soccer['_id']);
// このドキュメントを取得したときに、"likes" 配列の各項目がどのドキュメントのものなのかを
// 知ることができます
$people->insert(array("name" => "Fred", "likes" => array($trainRef, $soccerRef)));
?>
データベース参照は、ハイパーリンクのようなものととらえることができます。
別のドキュメントに関する一意なアドレスを提供しますが、
それを読み込んだり自動的にリンク先/参照先をたどったりはしません。
データベース参照は単なる連想配列であり、
MongoDBRef のインスタンスではありません。
そのため、このクラスは他のデータ型クラスとは多少異なります。
このクラスに含まれているのは、
データベース参照を操作するための静的メソッドだけです。
クラス概要
MongoDBRef
class MongoDBRef
{
public static array create
( string $collection
, mixed $id
[, string $database
] )
public static array get
( MongoDB $db
, array $ref
)
public static bool isRef
( mixed $ref
)
}
MongoMinKey クラス
警告
このクラスを定義している拡張モジュールは非推奨です。
かわりに MongoDB 拡張モジュールを使うべきです。
このクラスの代替として、以下が使えます。
はじめに
MongoMinKey はデータベースが使う特別な型で、
他のどんな BSON 型よりも小さいと評価されます。したがって、
特定のフィールドの昇順でクエリを並べ替えると、値が
MongoMinKey であるドキュメントが最初となります。
MongoMinKey にはフィールドやメソッド、定数はありません。
データベースに追加するときに使う、単なる "いちばん小さい" 値です。
注意:
MongoMinKey は、インデックス作成やシャーディングのために、MongoDB が内部的に利用するものです。
一般に、アプリケーション内でこのクラスを使う理由はありません。
クラス概要
MongoMinKey
class MongoMinKey
{
}
MongoMinKey の使用例
<?php
$collection->insert(array("task" => "lunch", "doBy" => new MongoMinKey));
$collection->insert(array("task" => "staff meeting", "doBy" => new MongoDate(strtotime("+4 days"))));
$cursor = $collection->find()->sort(array("doBy" => 1));
?>
このカーソルの中身は、まずlunchドキュメント、次にstaff meetingドキュメントとなります。
lunchドキュメントは、今後コレクションに何が追加されたとしても必ず最初になります
("doBy" フィールドが
MongoMinKey である別のドキュメントが追加されない限りは)。
MongoMaxKey クラス
警告
このクラスを定義している拡張モジュールは非推奨です。
かわりに MongoDB 拡張モジュールを使うべきです。
このクラスの代替として、以下が使えます。
はじめに
MongoMaxKey はデータベースが使う特別な型で、
他のどんな BSON 型よりも大きいと評価されます。したがって、
特定のフィールドの昇順でクエリを並べ替えると、値が
MongoMaxKey であるドキュメントが最後となります。
MongoMaxKey にはフィールドやメソッド、定数はありません。
データベースに追加するときに使う、単なる "いちばん大きい" 値です。
注意:
MongoMaxKey は、インデックス作成やシャーディングのために、MongoDB が内部的に利用するものです。
一般に、アプリケーション内でこのクラスを使う理由はありません。
クラス概要
MongoMaxKey
class MongoMaxKey
{
}
MongoMaxKey の使用例
<?php
$collection->insert(array("task" => "dishes", "doBy" => new MongoMaxKey));
$collection->insert(array("task" => "staff meeting", "doBy" => new MongoDate(strtotime("+4 days"))));
$cursor = $collection->find()->sort(array("doBy" => 1));
?>
このカーソルの中身は、まずstaff meetingドキュメント、次にdishesドキュメントとなります。
dishesドキュメントは、今後コレクションに何が追加されたとしても必ず最後になります
("doBy" フィールドが
MongoMaxKey である別のドキュメントが追加されない限りは)。
MongoTimestamp クラス
警告
このクラスを定義している拡張モジュールは非推奨です。
かわりに MongoDB 拡張モジュールを使うべきです。
このクラスの代替として、以下が使えます。
はじめに
MongoTimestamp は、MongoDB がレプリケーションやシャーディングで使う内部的な型です。
タイムスタンプ (エポックからの経過秒数) 4 バイトと増分 4 で構成されています。
この型は、時刻や日付の値を (ドキュメントの "createdAt" フィールドなどに) 格納するために使うものではありません。
注意:
MongoDB のレプリケーション oplog やシャーディングにかかわる書き込みをしているのでなければ、さっさと
MongoDate のほうに行きましょう。
このクラスはあなたの求めているものではありません。
クラス概要
MongoTimestamp
class MongoTimestamp
{
public
int
$sec
= 0
;
public
int
$inc
= 0
;
public __construct
([ int $sec = time()
[, int $inc
]] )
public string __toString
( void
)
}
|