IDs universalmente únicos (UUIDs)

Uma breve história dos UUIDs do MongoDB

Considere um UUID com a seguinte representação textual canônica:

00112233-4455-6677-8899-aabbccddeeff

Originalmente, o MongoDB representava UUIDs como valores BSON Binary do subtipo 3. Como o subtipo 3 não padronizou a ordem de bytes dos UUIDs durante a codificação, diferentes drivers do MongoDB codificaram UUIDs com diferentes ordens de bytes. Use as guias a seguir para comparar as maneiras como diferentes drivers da linguagem MongoDB codificaram o UUID anterior para Binary subtipo 3:

00112233-4455-6677-8899-aabbccddeeff

33221100-5544-7766-8899-aabbccddeeff

77665544-3322-1100-ffee-ddccbbaa9988

Para padronizar a ordem de bytes UUID, criamos Binary subtipo 4. Embora esse subtipo seja tratado de forma consistente em drivers do MongoDB, alguns sistemas do MongoDB ainda contêm valores UUID de subtipo 3.

UNSPECIFIED

Ao utilizar a representação UNSPECIFIED , o PyMongo decodifica valores BSON Binary para objetos Binary do mesmo subtipo. Para converter um objeto Binary em um objeto UUID nativo, chame o método Binary.as_uuid() e especifique um formato de representação UUID.

Se você tentar codificar um objeto UUID ao usar essa representação, o PyMongo gerará um ValueError. Para evitar isso, chame o método Binary.from_uuid() no UUID, conforme mostrado no exemplo a seguir:

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

O exemplo de código a seguir mostra como recuperar um documento contendo um UUID com a representação UNSPECIFIED e, em seguida, converter o valor em um objeto UUID . Para fazer isso, o código executa as seguintes etapas:

• Insere um documento que contém um campo uuid usando a representação CSHARP_LEGACY UUID.

• Recupera o mesmo documento usando a representação UNSPECIFIED . O PyMongo decodifica o valor do campo uuid como um objeto Binary .

• Chama o método as_uuid() para converter o valor do campo uuid para um objeto UUID do tipo CSHARP_LEGACY. Após ser convertido, este valor é idêntico ao UUID original inserido pelo PyMongo.

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

Ao usar a representação STANDARD UUID, o PyMongo codifica objetos UUID nativos para objetos Binary do subtipo 4 . Todos os drivers do MongoDB que usam a representação STANDARD tratam esses objetos da mesma maneira, sem alterações na ordem dos bytes.

Use a representação de UUID do STANDARD em todos os novos aplicativos e em todos os aplicativos que trabalham com UUIDs MongoDB pela primeira vez.

PYTHON_LEGACY

A representação PYTHON_LEGACY de UUID corresponde à representação legada de UUIDs usados por versões do PyMongo anteriores à v4.0. Ao usar a PYTHON_LEGACY representação UUID, o PyMongo codifica UUID objetos nativos para Binary 3 objetos do subtipo, preservando a mesma ordem de bytes da UUID.bytes propriedade .

Use a representação PYTHON_LEGACY UUID se o UUID que você está lendo do MongoDB foi inserido usando a representação PYTHON_LEGACY . Isso será verdade se ambos os critérios a seguir forem atendidos:

• O UUID foi inserido por um aplicativo usando uma versão do PyMongo anterior à v4.0.

• O aplicativo que inseriu o UUID não especificou a representação do UUID do STANDARD .

JAVA_LEGACY

A representação JAVA_LEGACY UUID corresponde à representação legada de UUIDs usada pelo MongoDB Java Driver. Ao usar a representação JAVA_LEGACY UUID, o PyMongo codifica objetos UUID Binary do subtipo 3 com ordem de bytes legada Java.

Use a representação JAVA_LEGACY UUID se o UUID que você está lendo do MongoDB foi inserido usando a representação JAVA_LEGACY . Isso será verdade se ambos os critérios a seguir forem atendidos:

• O UUID foi inserido por um aplicativo usando o driver Java do MongoDB.

• O aplicativo não especificou a representação do UUID do STANDARD .

CSHARP_LEGACY

A representação CSHARP_LEGACY UUID corresponde à representação legada de UUIDs usada pelo Driver MongoDB .NET/C#. Ao usar a representação CSHARP_LEGACY UUID, o PyMongo codifica objetos UUID Binary do subtipo 3 com a ordem de bytes legada de C#.

Use a representação CSHARP_LEGACY UUID se o UUID que você está lendo do MongoDB foi inserido usando a representação CSHARP_LEGACY . Isso será verdade se ambos os critérios a seguir forem atendidos:

• O UUID foi inserido por um aplicativo usando o driver MongoDB .NET/C#.

• O aplicativo não especificou a representação do UUID do STANDARD .

ValueError: não é possível codificar uuid.UUID nativo com UuidRepresentation.UNSPECIFIED

Esse erro resulta da tentativa de codificar um objeto UUID nativo para um objeto Binary quando a representação do UUID é UNSPECIFIED, conforme mostrado no exemplo de código a seguir:

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.

Em vez disso, você deve converter explicitamente um UUID nativo em um objeto Binary usando o método Binary.from_uuid() , conforme mostrado no exemplo a seguir:

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