Identificadores únicos universales (UUID)

Una breve historia de los UUID de MongoDB

Considere una UUID con la siguiente representación textual canónica:

00112233-4455-6677-8899-aabbccddeeff

Originalmente, MongoDB representaba los UUID como valores BSON Binary de subtipo 3. Debido a que el subtipo 3 no estandarizó el orden de los bytes de los UUID durante la codificación, diferentes drivers de MongoDB codificaron los UUID con diferentes órdenes de bytes. Utilice las siguientes pestañas para comparar las formas en que diferentes controladores de idiomas de MongoDB codificaron el UUID anterior en el subtipo Binary de 3:

00112233-4455-6677-8899-aabbccddeeff

33221100-5544-7766-8899-aabbccddeeff

77665544-3322-1100-ffee-ddccbbaa9988

Para estandarizar el orden de bytes UUID, creamos el subtipo Binary 4. Aunque este subtipo se maneja de manera coherente en todos los drivers de MongoDB, algunas implementaciones de MongoDB aún contienen valores UUID del subtipo 3.

UNSPECIFIED

Al utilizar la representación UNSPECIFIED, PyMongo decodifica los valores BSON Binary a objetos Binary del mismo subtipo. Para convertir un objeto Binary en un objeto nativo UUID, se debe llamar al método Binary.as_uuid() y especificar un formato de representación UUID.

Si intentas codificar un objeto UUID mientras usas esta representación, PyMongo genera un ValueError. Para evitar esto, llama al método Binary.from_uuid() en el UUID, como se muestra en el siguiente ejemplo:

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

El siguiente ejemplo de código muestra cómo recuperar un documento que contiene un UUID con la representación UNSPECIFIED y luego convertir el valor a un objeto UUID. Para hacerlo, el código realiza los siguientes pasos:

• Inserta un documento que contiene un campo uuid usando la representación UUID CSHARP_LEGACY.

• Recupera el mismo documento utilizando la representación UNSPECIFIED. PyMongo decodifica el valor del campo uuid como un objeto Binary.

• Llama al método as_uuid() para convertir el valor del campo uuid en un objeto UUID de tipo CSHARP_LEGACY. Después de la conversión, este valor es idéntico al UUID original introducido por 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

Cuando se utiliza la representación UUID STANDARD, PyMongo codifica los objetos UUID nativos en objetos de subtipo Binary 4. Todos los controladores de MongoDB que utilicen la representación STANDARD tratan estos objetos de la misma manera, sin cambios en el orden de bytes.

Utilice la representación UUID STANDARD en todas las aplicaciones nuevas y en todas aquellas aplicaciones que trabajen con UUIDs de MongoDB por primera vez.

PYTHON_LEGACY

La representación UUID PYTHON_LEGACY corresponde a la representación heredada de UUIDs utilizada por versiones de PyMongo anteriores a la v4.0. Al utilizar la representación UUID PYTHON_LEGACY, UUID nativas en PyMongo se codifican como objetos de subtipo Binary 3, preservando el mismo orden de bytes que la propiedad UUID.bytes.

Utiliza la representación UUID PYTHON_LEGACY si el UUID que estás leyendo desde MongoDB se insertó utilizando la representación PYTHON_LEGACY. Esto será cierto si se cumplen ambos de los siguientes criterios:

• El UUID fue insertado por una aplicación que utiliza una versión de PyMongo anterior a v4.0.

• La aplicación que insertó el UUID no especificó la representación UUID de STANDARD.

JAVA_LEGACY

La representación UUID de JAVA_LEGACY corresponde a la representación heredada de UUIDs utilizada por el controlador Java de MongoDB. Al usar la representación UUID JAVA_LEGACY, PyMongo codifica objetos nativos UUID en objetos de subtipo Binary 3 con el orden de bytes heredado de Java.

Utiliza la representación UUID JAVA_LEGACY si el UUID que estás leyendo desde MongoDB se insertó utilizando la representación JAVA_LEGACY. Esto será cierto si se cumplen ambos de los siguientes criterios:

• El UUID fue insertado por una aplicación que utiliza el MongoDB Java Driver.

• La aplicación no especificó la representación UUID de STANDARD.

CSHARP_LEGACY

La representación UUID CSHARP_LEGACY corresponde a la representación heredada de UUIDs utilizada por el driver .NET/C# de MongoDB. Al usar la representación UUID CSHARP_LEGACY, PyMongo codifica los objetos nativos UUID en objetos de subtipo Binary 3 con el orden de bytes heredado de C#.

Utiliza la representación UUID CSHARP_LEGACY si el UUID que estás leyendo desde MongoDB se insertó utilizando la representación CSHARP_LEGACY. Esto será cierto si se cumplen ambos de los siguientes criterios:

• El UUID fue insertado por una aplicación utilizando el controlador MongoDB .NET/C#.

• La aplicación no especificó la representación UUID de STANDARD.

ValueError: no se puede codificar uuid.UUID nativo con UuidRepresentation.UNSPECIFIED

Este error se produce al intentar codificar un objeto nativo UUID a un objeto Binary cuando la representación UUID es UNSPECIFIED, como se muestra en el siguiente ejemplo de código:

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.

En cambio, debes convertir explícitamente un UUID nativo en un objeto Binary usando el método Binary.from_uuid(), como se muestra en el siguiente ejemplo:

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