BSON 튜토리얼

쓰기

쓰기 위해 ByteBuffer 을 만들려면(예: BSON으로 직렬화), 인수 없이 BSON::ByteBuffer 을 인스턴스화합니다:

buffer = BSON::ByteBuffer.new

변환 없이 바이트 버퍼에 원시 바이트를 쓰려면 put_byte 및 put_bytes 메서드를 사용합니다. 바이트 문자열을 인수로 사용하여 이 문자열을 버퍼에 복사합니다. put_byte 는 인수가 길이가 1인 문자열을 강제합니다. put_bytes 은 모든 길이의 문자열을 허용합니다. 문자열에는 null 바이트가 포함될 수 있습니다.

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

후속 쓰기 메서드는 BSON 사양 에서 특정 유형의 객체를 씁니다. . 메서드 이름에 put_int32 유형은 인수의 유형보다 우선합니다. .

UTF-8 문자열(BSON type 0x02)을 바이트 버퍼에 쓰려면 put_string 을 사용합니다.

buffer.put_string("hello, world")

BSON 문자열은 항상 UTF-8로 인코딩됩니다. 따라서 인수는 UTF-8 또는 UTF-8로 변환 가능한 인코딩(예: 바이너리가 아님). 인수가 UTF-8 이외의 인코딩으로 된 경우 문자열이 먼저 UTF-8로 변환되고 UTF-8로 인코딩된 버전이 버퍼에 기록됩니다. 문자열은 청구된 인코딩으로 유효해야 하며, 인코딩이 UTF-8인 경우 유효한 UTF-8이어야 합니다. 문자열에 null 바이트가 포함될 수 있습니다.

BSON 사양은 예를 들어 문서 키에 사용되는 CString 형식도 정의합니다. 버퍼에 CString을 쓰려면 put_cstring 을 사용합니다.

buffer.put_cstring("hello, world")

일반 문자열과 마찬가지로 BSON의 CStrings는 UTF-8로 인코딩되어야 합니다. 인수가 UTF-8이 아닌 경우 UTF-8로 변환되고 결과 문자열이 버퍼에 기록됩니다. 와 달리 put_string 에 제공된 인수의 UTF-8 인코딩은 put_cstring BSON의 CString 직렬화 형식이 null로 종료되므로 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)

직렬화된 데이터를 바이트 문자열로 가져오려면(예: 소켓을 통해 데이터를 보내려면) 버퍼에서 to_s 를 호출합니다.

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

읽기

읽기용 ByteBuffer 을(를) 만들려면(예: BSON에서 역직렬화), 바이트 문자열을 인수로 사용하여 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 코드의 문자열을 나타냅니다.

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

BSON::CodeWithScope

값 해시가 있는 JavaScript 코드 문자열을 나타냅니다.

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

BSON::DBRef

이는 DBRef의 collection, 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

이는 모든 키를 문자열로 저장하지만 기호 키를 사용하여 액세스를 허용하는 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비트 소수점 기반 부동 소수점 값을 나타냅니다.

# 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 기호 유형을 더 이상 사용하지 않고 대신 문자열을 사용하도록 권장합니다.

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

기본적으로 BSON 라이브러리는 Symbol 해시 값을 문자열로 인코딩하고, 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 정규 표현식 엔진 을 사용하여 구현됩니다. 은 Oniguruma 의 포크입니다. . 두 정규 표현식 구현은 일반적으로 동일한 기능을 제공하지만 아래에 설명된 대로 몇 가지 중요한 구문 차이점이 있습니다.

안타깝게도 프로그래밍 방식으로 PCRE 정규 표현식을 동등한 Ruby 정규 표현식으로 변환하는 간단한 방법이 없으며, 현재 PCRE에 대한 Ruby 바인딩도 없습니다.

BSON::Regexp::Raw 클래스

프로그래밍 방식으로 PCRE 정규 표현식을 동등한 Ruby 정규 표현식으로 변환하는 간단한 방법이 없으므로, bson- Ruby는 MongoDB/PCRE 정규 표현식을 보관하기 위한 BSON::Regexp::Raw 클래스를 제공합니다. 이 문서에서는 이 클래스의 인스턴스를 "BSON 정규 표현식"이라고 합니다.

이 클래스의 인스턴스는 정규 표현식 텍스트를 문자열로 사용하고 선택적 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 수정자로 변환되었으며, 마지막 두 예제는 원래의 BSON 정규 표현식이 서로 다른 의미를 가졌음에도 불구하고 동일한 정규 표현식으로 변환되었다는 점에 유의하세요.

BSON 정규 표현식이 이식성이 없는 ^ 및 $ 앵커를 사용하는 경우, Ruby 정규 표현식으로 변환하면 의미가 변경될 수 있습니다.

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

Ruby 정규 표현식이 BSON 정규 표현식으로 변환되는 경우(예: 쿼리의 일부로 서버에 전송) BSON 정규 표현식에는 항상 ^ 및 의 동작을 반영하는 m 수정자 세트가 있습니다. $ 앵커를 사용합니다.

읽기 및 쓰기

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 클래스 메서드를 구현합니다. 두 클래스의 메서드는 모두 위에서 설명한 대로 compile 메서드를 사용하여 Ruby 정규 표현식으로 변환해야 하는 BSON::Regexp::Raw 인스턴스를 반환합니다.

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/