범용 고유 ID(UUID)

MongoDB UUID의 짧은 역사

다음과 같은 표준 텍스트 표현을 가진 UUID를 가정해 보겠습니다.

00112233-4455-6677-8899-aabbccddeeff

원래 MongoDB는 UUID를 3 하위 유형의 BSON Binary 값으로 표시했습니다. 하위 유형 3 가 인코딩 중에 UUID의 바이트 순서를 표준화하지 않았기 때문에 서로 다른 MongoDB 드라이버가 서로 다른 바이트 순서로 UUID를 인코딩했습니다. 다음 탭을 사용하여 다양한 MongoDB 언어 드라이버가 앞의 UUID를 Binary 하위 유형 3 로 인코딩한 방식을 비교합니다.

UUID 바이트 순서를 표준화하기 위해 Binary 하위 유형 4 을 만들었습니다. 이 하위 유형은 MongoDB 드라이버 전체에서 일관되게 처리되지만, 일부 MongoDB 배포에는 여전히 하위 유형 3 의 UUID 값이 포함되어 있습니다.

UNSPECIFIED

UNSPECIFIED 표현을 사용할 때 PyMongo는 BSON Binary 값을 동일한 하위 유형의 Binary 객체로 디코딩합니다. Binary 객체를 네이티브 UUID 객체로 변환하려면 Binary.as_uuid() 메서드를 호출하고 UUID 표현 형식을 지정합니다.

이 표현을 사용하는 동안 UUID 객체를 인코딩하려고 하면 PyMongo가 ValueError 을 발생시킵니다. 이를 방지하려면 다음 예제와 같이 UUID에서 Binary.from_uuid() 메서드를 호출합니다.

explicit_binary = Binary.from_uuid(uuid4(), UuidRepresentation.STANDARD)

다음 코드 예시에서는 UNSPECIFIED 표현으로 UUID가 포함된 문서를 조회한 다음 값을 UUID 객체로 변환하는 방법을 보여 줍니다. 이를 위해 코드는 다음 단계를 수행합니다.

• CSHARP_LEGACY UUID 표현을 사용하여 uuid 필드가 포함된 문서를 삽입합니다.

• UNSPECIFIED 표현을 사용하여 동일한 문서를 조회합니다. PyMongo는 uuid 필드의 값을 Binary 객체로 디코딩합니다.

• as_uuid() 메서드를 호출하여 uuid 필드의 값을 CSHARP_LEGACY 유형의 UUID 객체로 변환합니다. 변환된 후 이 값은 PyMongo에서 삽입한 원래 UUID와 동일합니다.

from bson.codec_options import CodecOptions, DEFAULT_CODEC_OPTIONS
from bson.binary import Binary, UuidRepresentation
from uuid import uuid4
# Using UuidRepresentation.CSHARP_LEGACY
csharp_opts = CodecOptions(uuid_representation=UuidRepresentation.CSHARP_LEGACY)
# Store a legacy C#-formatted UUID
input_uuid = uuid4()
collection = client.testdb.get_collection('test', codec_options=csharp_opts)
collection.insert_one({'_id': 'foo', 'uuid': input_uuid})
# Using UuidRepresentation.UNSPECIFIED
unspec_opts = CodecOptions(uuid_representation=UuidRepresentation.UNSPECIFIED)
unspec_collection = client.testdb.get_collection('test', codec_options=unspec_opts)
# UUID fields are decoded as Binary when UuidRepresentation.UNSPECIFIED is configured
document = unspec_collection.find_one({'_id': 'foo'})
decoded_field = document['uuid']
assert isinstance(decoded_field, Binary)
# Binary.as_uuid() can be used to convert the decoded value to a native UUID
decoded_uuid = decoded_field.as_uuid(UuidRepresentation.CSHARP_LEGACY)
assert decoded_uuid == input_uuid

STANDARD

STANDARD UUID 표현을 사용할 때 PyMongo는 네이티브 UUID 객체를 Binary 하위 유형 4 객체로 인코딩합니다. STANDARD 표현을 사용하는 모든 MongoDB 드라이버는 바이트 순서를 변경하지 않고 이러한 객체를 동일한 방식으로 처리합니다.

모든 새 애플리케이션과 MongoDB UUID로 처음 작업하는 모든 애플리케이션에서 STANDARD UUID 표현을 사용합니다.

PYTHON_LEGACY

PYTHON_LEGACY UUID 표현은 v4.0 이전 PyMongo 버전에서 사용된 UUID의 레거시 표현에 해당합니다. PYTHON_LEGACY UUID 표현을 사용할 때 PyMongo는 UUID.bytes 속성과 동일한 바이트 순서를 유지하면서 네이티브 UUID 객체를 Binary 하위 유형 3 객체로 인코딩합니다.

MongoDB에서 읽는 UUID가 PYTHON_LEGACY 표현을 사용하여 삽입된 경우 PYTHON_LEGACY UUID 표현을 사용합니다. 이는 다음 기준이 두 가지 모두 충족되는 경우에 해당됩니다.

• UUID가 v4.0 이전 버전의 PyMongo를 사용하는 애플리케이션에 의해 삽입되었습니다.

• UUID를 삽입한 애플리케이션이 STANDARD UUID 표현을 지정하지 않았습니다.

JAVA_LEGACY

JAVA_LEGACY UUID 표현은 MongoDB Java 드라이버에서 사용하는 UUID의 레거시 표현에 해당합니다. JAVA_LEGACY UUID 표현을 사용할 때 PyMongo는 네이티브 UUID 객체를 Java 레거시 바이트 순서로 Binary 하위 유형 3 객체로 인코딩합니다.

MongoDB에서 읽는 UUID가 JAVA_LEGACY 표현을 사용하여 삽입된 경우 JAVA_LEGACY UUID 표현을 사용합니다. 이는 다음 기준이 두 가지 모두 충족되는 경우에 해당됩니다.

• UUID는 MongoDB Java 드라이버를 사용하는 애플리케이션에 의해 삽입되었습니다.

• 애플리케이션이 STANDARD UUID 표현을 지정하지 않았습니다.

CSHARP_LEGACY

CSHARP_LEGACY UUID 표현은 MongoDB .NET/C# 드라이버에서 사용하는 UUID의 레거시 표현에 해당합니다. CSHARP_LEGACY UUID 표현을 사용할 때 PyMongo는 네이티브 UUID 객체를 C# 레거시 바이트 순서로 Binary 하위 유형 3 객체로 인코딩합니다.

MongoDB에서 읽는 UUID가 CSHARP_LEGACY 표현을 사용하여 삽입된 경우 CSHARP_LEGACY UUID 표현을 사용합니다. 이는 다음 기준이 두 가지 모두 충족되는 경우에 해당됩니다.

• UUID는 MongoDB .NET/C# 드라이버를 사용하는 애플리케이션에서 삽입되었습니다.

• 애플리케이션이 STANDARD UUID 표현을 지정하지 않았습니다.

ValueError: 네이티브 uuid.UUID를 UuidRepresentation.UNSPECIFIED로 인코딩할 수 없습니다.

이 오류는 다음 코드 예시와 같이 UUID 표현이 UNSPECIFIED 일 때 네이티브 UUID 객체를 Binary 객체로 인코딩하려고 시도할 때 발생합니다.

unspecified_collection.insert_one({'_id': 'bar', 'uuid': uuid4()})
Traceback (most recent call last):
...
ValueError: cannot encode native uuid.UUID with UuidRepresentation.UNSPECIFIED.
UUIDs can be manually converted to bson.Binary instances using bson.Binary.from_uuid()
or a different UuidRepresentation can be configured. See the documentation for
UuidRepresentation for more information.

대신 다음 예와 같이 Binary.from_uuid() 메서드를 사용하여 네이티브 UUID를 Binary 객체로 명시적으로 변환해야 합니다.

explicit_binary = Binary.from_uuid(uuid4(), UuidRepresentation.STANDARD)
unspec_collection.insert_one({'_id': 'bar', 'uuid': explicit_binary})