BSON チュートリアル

書込み

書込み (write) 用のByteBufferを作成するには（つまり BSON に直列化するなど）、引数なしでBSON::ByteBufferをインスタンス化します。

buffer = BSON::ByteBuffer.new

変換されない未加工バイトをバイトバッファに書込むには、 メソッドとput_byte put_bytesメソッドを使用します。バイト string を引数として受け取り、この string をバッファにコピーします。 put_byte では、引数が長さ 1 のstringであることが強制されます。 put_bytes は任意の長さの文字列を受け入れます。 string には null バイトを含めることができます。

buffer.put_byte("\x00")
buffer.put_bytes("\xff\xfe\x00\xfd")

後続の書込みメソッドは、 BSON 仕様 の特定のタイプのオブジェクトを書込みます 。メソッド名で示される型は引数の型よりも優先されることに注意してください。たとえば、浮動小数点値がput_int32に与えられている場合、その値は強制的に整数に変換され、結果の整数はバイト バッファに書き込まれます。 。

UTF-8 string（BSON 型 0x02）をバイト バッファに書込むには、 put_stringを使用します。

buffer.put_string("hello, world")

BSON string は常に UTF-8 でエンコードされることに注意してください。 したがって、引数は UTF-8 または UTF-8 に変換可能なエンコーディング のいずれかである必要があります（ バイナリではありません）。 引数が UTF-8 以外のエンコードにある場合、string はまず UTF-8 に変換され、UTF-8 でエンコードされたバージョンがバッファに書き込まれます。 string は、エンコーディングが UTF-8 の場合は有効な UTF-8 であるなど、要求されるエンコーディングが有効である必要があります。 string には null バイトが含まれる場合があります。

BSON 仕様 では、ドキュメント キーの例として使用される CString 型 も定義されています。 CString をバッファに書き込むには、 put_cstringを使用します。

buffer.put_cstring("hello, world")

通常の文字列と同様に、BSON の CString は UTF-8 でエンコードされる必要があります。 引数が UTF-8 にない場合は、UTF-8 に変換され、結果のstringがバッファに書き込まれます。 put_stringとは異なり、 put_cstringに付与される引数の UTF-8 エンコーディングには、null バイトを含めることはできません。BSON の CString 直列化形式は null で終了するためです。

put_stringとは異なり、 put_cstringは記号と整数も受け入れます。 すべての場合、引数は書き込まれる前に文字列化されます。

buffer.put_cstring(:hello)
buffer.put_cstring(42)

32 ビット整数または 64 ビット整数をバイトput_int32 put_int64バッファに書き込むには、それぞれ メソッドと メソッドを使用します。Ruby の整数は任意に大きくなることに注意してください。書き込まれている値が 32 ビット整数または 64 ビット整数の範囲を超える場合、 put_int32とput_int64はRangeErrorを発生させます。

buffer.put_int32(12345)
buffer.put_int64(123456789012345)

64 ビットの浮動小数点値をバイト バッファに書込むには、 put_doubleを使用します。

buffer.put_double(3.14159)

シリアル化されたデータをバイトstringとして取得するには（ソケット経由でデータを送信する場合など）、バッファで to_s を呼び出します。

buffer = BSON::ByteBuffer.new
buffer.put_string('testing')
socket.write(buffer.to_s)

読み取り

読み取り用のByteBufferを作成するには（つまり BSONからの逆直列化）、バイトstringを引数として BSON::ByteBuffer をインスタンス化します。

buffer = BSON::ByteBuffer.new(string) # a read mode buffer.

バッファからの読み取りは、次の API 経由で行われます。

buffer.get_byte # Pulls a single byte from the buffer.
buffer.get_bytes(value) # Pulls n number of bytes from the buffer.
buffer.get_cstring # Pulls a null-terminated string from the buffer.
buffer.get_double # Pulls a 64-bit floating point from the buffer.
buffer.get_int32 # Pulls a 32-bit integer (4 bytes) from the buffer.
buffer.get_int64 # Pulls a 64-bit integer (8 bytes) from the buffer.
buffer.get_string # Pulls a UTF-8 string from the buffer.

バッファの先頭から読み取りを再開するには、 rewindを使用します。

buffer.rewind

BSON::Binary

任意のバイナリ データを保存するには、 BSON::Binaryオブジェクトを使用します。 Binaryオブジェクトは、次のようにバイナリ文字列から構築できます。

BSON::Binary.new("binary_string")
# => <BSON::Binary:0x47113101192900 type=generic data=0x62696e6172795f73...>

デフォルトでは、 Binaryオブジェクトは BSON バイナリ サブタイプ 0（ :generic ）で作成されます。 サブタイプを明示的に指定して、バイトが特定のタイプのデータをエンコードすることを示すことができます。

BSON::Binary.new("binary_string", :user)
# => <BSON::Binary:0x47113101225420 type=user data=0x62696e6172795f73...>

有効なサブタイプは、 :generic 、 :function 、 :old 、 :uuid_old 、 :uuid 、 :md5 、 :userです。

データとサブタイプは、次のように、 dataとtype属性を使用してBinaryインスタンスから取得できます。

binary = BSON::Binary.new("binary_string", :user)
binary.data
=> "binary_string"
binary.type
=> :user

str = "binary_string"
str.encoding
# => #<Encoding:US-ASCII>
binary = BSON::Binary.new(str)
binary.data
# => "binary_string"
binary.data.encoding
# => #<Encoding:ASCII-8BIT>

uuid_str = "00112233-4455-6677-8899-aabbccddeeff"
BSON::Binary.from_uuid(uuid_str)
# => <BSON::Binary:0x46986653612880 type=uuid data=0x0011223344556677...>

binary = BSON::Binary.new("\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF".force_encoding('BINARY'), :uuid)
=> <BSON::Binary:0x46942046606480 type=uuid data=0x0011223344556677...>
binary.to_uuid
=> "00112233-4455-6677-8899aabbccddeeff"

binary = BSON::Binary.from_uuid(uuid_str, :standard)
binary.to_uuid(:standard)

binary = BSON::Binary.new("\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF".force_encoding('BINARY'), :uuid_old)
=> <BSON::Binary:0x46942046606480 type=uuid data=0x0011223344556677...>
binary.to_uuid
# => ArgumentError (Representation must be specified for BSON::Binary objects of type :uuid_old)
binary.to_uuid(:csharp_legacy)
# => "33221100-5544-7766-8899aabbccddeeff"
binary.to_uuid(:java_legacy)
# => "77665544-3322-1100-ffeeddccbbaa9988"
binary.to_uuid(:python_legacy)
# => "00112233-4455-6677-8899aabbccddeeff"

uuid_str = "00112233-4455-6677-8899-aabbccddeeff"
BSON::Binary.from_uuid(uuid_str, :csharp_legacy)
# => <BSON::Binary:0x46986653650480 type=uuid_old data=0x3322110055447766...>
BSON::Binary.from_uuid(uuid_str, :java_legacy)
# => <BSON::Binary:0x46986653663960 type=uuid_old data=0x7766554433221100...>
BSON::Binary.from_uuid(uuid_str, :python_legacy)
# => <BSON::Binary:0x46986653686300 type=uuid_old data=0x0011223344556677...>

BSON::Binary.from_uuid('77665544-3322-1100-ffeeddccbbaa9988',:java_legacy).to_uuid(:csharp_legacy)
# => "33221100-5544-7766-8899aabbccddeeff"

BSON::Code

JavaScript コードの string を表します。

BSON::Code.new("this.value = 5;")

BSON::CodeWithScope

stringJavaScript値のハッシュを持つ コードの を表します。

BSON::CodeWithScope.new("this.value = age;", age: 5)

BSON::DBRef

これは、DBRef のコレクション、ID、データベースへのアクセスを提供するBSON::Documentのサブクラスです。

BSON::DBRef.new({"$ref" => "collection", "$id" => "id"})
BSON::DBRef.new({"$ref" => "collection", "$id" => "id", "database" => "db"})

bson = {"$ref" => "collection", "$id" => "id"}.to_bson.to_s
loaded = Hash.from_bson(BSON::ByteBuffer.new(bson))
=> {"$ref"=>"collection", "$id"=>"id"}
loaded.class
=> BSON::DBRef

MongoDB Ruby ドライバー バージョン 2.17 以前との下位互換性のため、レガシードライバー API を使用してBSON::DBRefを構築することもできます。 この API は非推奨であり、 bson-rubyの将来のバージョンでは削除される予定です。

BSON::DBRef.new("collection", BSON::ObjectId('61eeb760a15d5d0f9f1e401d'))
BSON::DBRef.new("collection", BSON::ObjectId('61eeb760a15d5d0f9f1e401d'), "db")

BSON::Document

これは、すべてのキーを string として保存しますが、シンボルキーによるアクセスは許可するHashのサブクラスです。

BSON::Document[:key, "value"]
BSON::Document.new

bson = {test: 1}.to_bson.to_s
loaded = Hash.from_bson(BSON::ByteBuffer.new(bson))
=> {"test"=>1}
loaded.class
=> BSON::Document

BSON::MaxKey

常に別の値と比較される BSON の値を表します。

BSON::MaxKey.new

BSON::MinKey

常に別の値と比較される BSON の値を表します。

BSON::MinKey.new

BSON::ObjectId

特定のマシン上のオブジェクトに対する 12 バイトの一意の識別子を表します。

BSON::ObjectId.new

BSON::Timestamp

開始値と増分値を持つ特別な時間を表します。

BSON::Timestamp.new(5, 30)

BSON::Undefined

指定されなかった値のプレースホルダーを表します。

BSON::Undefined.new

BSON::Decimal128

正確な精度で小数の丸めをエミュレートできる 128 ビットの 10 進数ベースの浮動小数点値を表します。

# Instantiate with a String
BSON::Decimal128.new("1.28")
# Instantiate with a BigDecimal
d = BigDecimal(1.28, 3)
BSON::Decimal128.new(d)

Symbol

BSON 仕様 は、Ruby Symbol値のラウンドトリップを許可する シンボル タイプ を定義します（つまり Ruby Symbol``is encoded into a BSON symbol and a BSON symbol is decoded into a Ruby ``Symbol ）。 ただし、ほとんどのプログラミング言語にはネイティブのシンボル型がないため、相互運用性を高めるために、MongoDB は BSON シンボル型を非推奨にし、代わりに string を使用することを推奨しています。

Hash.from_bson({foo: 'bar'}.to_bson)
# => {"foo"=>"bar"}
Hash.from_bson({1 => 2}.to_bson)
# => {"1"=>2}

デフォルトでは、BSON ライブラリはSymbolハッシュ値を string としてエンコードし、BSON シンボルを Ruby Symbol値にデコードします。

{foo: :bar}.to_bson.to_s
# => "\x12\x00\x00\x00\x02foo\x00\x04\x00\x00\x00bar\x00\x00"
# 0x02 is the string type
Hash.from_bson(BSON::ByteBuffer.new("\x12\x00\x00\x00\x02foo\x00\x04\x00\x00\x00bar\x00\x00".force_encoding('BINARY')))
# => {"foo"=>"bar"}
# 0x0E is the symbol type
Hash.from_bson(BSON::ByteBuffer.new("\x12\x00\x00\x00\x0Efoo\x00\x04\x00\x00\x00bar\x00\x00".force_encoding('BINARY')))
# => {"foo"=>:bar}

Ruby 記号のエンコーディングを BSON 記号に強制するには、Ruby 記号をBSON::Symbol::Rawでラップします。

{foo: BSON::Symbol::Raw.new(:bar)}.to_bson.to_s
# => "\x12\x00\x00\x00\x0Efoo\x00\x04\x00\x00\x00bar\x00\x00"

Ruby と MongoDB の正規表現

MongoDB サーバーは 、PCRE ライブラリを使用して実装された Perl 互換正規表現を使用します および Ruby 正規表現 は、 Onigmo 正規表現エンジン を使用して実装されています は、 Atlas のノードであり、 。これらの 2 つの正規表現の実装は通常同等の機能を提供しますが、以下に説明するようにいくつかの重要な構文の違いがあります。

残念ながら、PCRE 正規表現をプログラムで同等の Ruby 正規表現に変換する簡単な方法はなく、PCRE の Ruby バインディングは現在存在しません。

BSON::Regexp::Raw クラス

PCRE 正規表現をプログラムで同等の Ruby 正規表現に変換する簡単な方法がないため、bson- Ruby は MongoDB / PCRE 正規表現を保持するためのBSON::Regexp::Rawクラスを提供します。 このドキュメントでは、このクラスのインスタンスは「BSON 正規表現」と呼ばれています。

このクラスのインスタンスは、正規表現テキストを string と任意の PCRE 修飾子として使用して作成できます。

BSON::Regexp::Raw.new("^b403158")
# => #<BSON::Regexp::Raw:0x000055df63186d78 @pattern="^b403158", @options="">
BSON::Regexp::Raw.new("^Hello.world$", "s")
# => #<BSON::Regexp::Raw:0x000055df6317f028 @pattern="^Hello.world$", @options="s">

BSON::Regexpモジュールは Ruby Regexpクラスに含まれているため、 BSON::プレフィックスは省略できます。

Regexp::Raw.new("^b403158")
# => #<BSON::Regexp::Raw:0x000055df63186d78 @pattern="^b403158", @options="">
Regexp::Raw.new("^Hello.world$", "s")
# => #<BSON::Regexp::Raw:0x000055df6317f028 @pattern="^Hello.world$", @options="s">

正規表現の変換

Ruby 正規表現を BSON 正規表現に変換するには、次のようにBSON::Regexp::Rawオブジェクトをインスタンス化します。

regexp = /^Hello.world/
bson_regexp = BSON::Regexp::Raw.new(regexp.source, regexp.options)
# => #<BSON::Regexp::Raw:0x000055df62e42d60 @pattern="^Hello.world", @options=0>

BSON::Regexp::Rawコンストラクターは Ruby 数値オプションと PCRE 修飾子文字列の両方を受け入れることに注意してください。

BSON 正規表現を Ruby 正規表現に変換するには、BSON 正規表現でcompileメソッドを呼び出します。

bson_regexp = BSON::Regexp::Raw.new("^hello.world", "s")
bson_regexp.compile
# => /^hello.world/m
bson_regexp = BSON::Regexp::Raw.new("^hello", "")
bson_regexp.compile
# => /^hello.world/
bson_regexp = BSON::Regexp::Raw.new("^hello.world", "m")
bson_regexp.compile
# => /^hello.world/

最初の例ではs PCRE 修飾子はm Ruby 修飾子に変換され、最後の 2 つの例では、元の BSON 正規表現の意味が異なる場合でも、同じ正規表現に変換されていることに注意してください。

BSON 正規表現で移植性のない^と$アンカーが使用される場合、Ruby 正規表現への変換でその意味が変わる可能性があります。

BSON::Regexp::Raw.new("^hello.world", "").compile =~ "42\nhello world"
# => 3

Ruby 正規表現が BSON 正規表現に変換される場合（たとえば、クエリの一部としてサーバーに送信する場合など）、BSON 正規表現には常に^と$の動作を反映するm修飾子が設定されます。 Ruby 正規表現のアンカー。

読み取りと書込み

Ruby と BSON 正規表現はどちらも、BSON への直列化用にto_bsonメソッドを実装しています。

regexp_ruby = /^b403158/
# => /^b403158/
regexp_ruby.to_bson
# => #<BSON::ByteBuffer:0x007fcf20ab8028>
_.to_s
# => "^b403158\x00m\x00"
regexp_raw = Regexp::Raw.new("^b403158")
# => #<BSON::Regexp::Raw:0x007fcf21808f98 @pattern="^b403158", @options="">
regexp_raw.to_bson
# => #<BSON::ByteBuffer:0x007fcf213622f0>
_.to_s
# => "^b403158\x00\x00"

RegexpクラスとBSON::Regexp::Rawクラスは両方とも、BSON バイト バッファから正規表現を逆直列化するfrom_bsonクラス メソッドを実装しています。 両方のクラスのメソッドはBSON::Regexp::Rawインスタンスを返します。これは、上記で説明したようにcompileメソッドを使用して Ruby 正規表現に変換する必要があります。

byte_buffer = BSON::ByteBuffer.new("^b403158\x00\x00")
regex = Regexp.from_bson(byte_buffer)
# => #<BSON::Regexp::Raw:0x000055df63100d40 @pattern="^b403158", @options="">
regex.pattern
# => "^b403158"
regex.options
# => ""
regex.compile
# => /^b403158/