(Opcional) Crear un esquema (usuarios avanzados) - AWS Clean Rooms
Esquemas de tablas mapeados y posicionales

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

(Opcional) Crear un esquema (usuarios avanzados)

La creación manual de esquemas está reserva para los usuarios avanzados.

A continuación se describe el formato del archivo de JSON esquema para los archivos de entrada con o sin encabezados de columna. Los usuarios avanzados pueden escribir o modificar el esquema directamente si lo desean.

nota

El cliente de cifrado de C3R puede ayudarlo a crear un esquema mediante el proceso interactivo descrito en Ejemplo: Generar un esquema de cifrado con columnas sealed, fingerprint y columnas o mediante la creación de una plantilla stub.

Esquemas de tablas mapeados y posicionales

En la siguiente sección se describen dos tipos de esquemas de tabla:

  • Esquema de tabla mapeado: este esquema se usa para cifrar archivos .csv con una fila de encabezado y archivos Apache Parquet.

  • Esquema de tabla posicional: este esquema se usa para cifrar archivos .csv sin fila de encabezado.

El cliente de cifrado de C3R puede cifrar un archivo tabular para una colaboración. Para ello, debe tener un archivo de esquema correspondiente que especifique cómo se debe derivar la salida cifrada a partir de la entrada.

El cliente de cifrado de C3R puede ayudar a generar un esquema para un archivo INPUT ejecutando el comando de esquema del cliente de cifrado de C3R en la línea de comandos. Un ejemplo de comando es java -jar c3r-cli.jar schema --interactive INPUT.

El esquema especifica la siguiente información:

  1. Qué columnas de origen se asignan a qué columnas transformadas en el archivo de salida mediante sus nombres de encabezado (esquemas mapeados) o su posición (esquemas posicionales)

  2. Qué columnas de destino van a permanecer como cleartext

  3. Qué columnas de destino se van a cifrar para las consultas SELECT

  4. Qué columnas de destino se van a cifrar para las consultas JOIN

Esta información está codificada en un archivo de JSON esquema específico de una tabla, que consta de un único objeto cuyo headerRow campo es un valor booleano. El valor debe ser true para los archivos Parquet y los archivos .csv con fila de encabezado, y false para el resto.

Esquema de la tabla mapeado

El esquema mapeado tiene la siguiente forma.

{
  "headerRow": true,
  "columns": [
    {
      "sourceHeader": STRING,
      "targetHeader": STRING,
      "type": TYPE,
      "pad": PAD
    },
    ...
  ]
}

Si headerRow es asítrue, el siguiente campo del objeto escolumns, que contiene una matriz de esquemas de columnas que asignan los encabezados de origen a los encabezados de destino (es decir, JSON objetos que describen lo que deben contener las columnas de salida).

  • sourceHeader: el nombre del encabezado STRING de la columna de origen a partir de cual se derivan los datos.

    nota

    Una misma columna de origen se puede utilizar para varias columnas de destino.

    Una columna del archivo de entrada que no aparezca enumerada como sourceHeader en ninguna parte del esquema no aparecerá en el archivo de salida.

  • targetHeader: el nombre del encabezado STRING de la columna correspondiente del archivo de salida.

    nota

    Este campo es opcional para los esquemas mapeados. Si se omite este campo, sourceHeader se reutiliza para el nombre del encabezado en el archivo de salida. Se anexa _fingerprint o _sealed si la columna de salida es una columna fingerprint o una columna sealed, respectivamente.

  • type: el TYPE de la columna de destino del archivo de salida. Es decir, una de las columnas cleartext, sealed o fingerprint dependiendo de cómo se vaya a utilizar la columna en la colaboración.

  • pad: un campo de un objeto de esquema de columnas que solo está presente cuando TYPE es sealed. Su valor correspondiente de PAD es un objeto que describe cómo deben rellenarse los datos antes del cifrado.

    {
  "type": PAD_TYPE,
  "length": INT
}

    Para especificar el relleno previo al cifrado, se utiliza type y length de la siguiente manera:

    • PAD_TYPE como none: no se aplicará ningún relleno a los datos de la columna y el campo length no es aplicable (es decir, se omite).

    • PAD_TYPE como fixed: los datos de la columna se rellenan hasta el número de bytes especificado, length.

    • PAD_TYPE como max: los datos de la columna se rellenan hasta el tamaño de la longitud en bytes del valor más largo, más length bytes adicionales.

El siguiente es un ejemplo de esquema mapeado, con una columna de cada tipo.

{
  "headerRow": true,
  "columns": [
    {
      "sourceHeader": "FullName",
      "targetHeader": "name",
      "type": "cleartext"
    },
    {
      "sourceHeader": "City",
      "targetHeader": "city_sealed",
      "type": "sealed",
      "pad": {
        "type": "max",
        "length": 16
      }
    },
    {
      "sourceHeader": "PhoneNumber",
      "targetHeader": "phone_number_fingerprint",
      "type": "fingerprint"
    },
    {
      "sourceHeader": "PhoneNumber",
      "targetHeader": "phone_number_sealed",
      "type": "sealed",
      "pad": {
        "type": "fixed",
        "length": 20
      }
    }
  ]
}

Un ejemplo más complejo sería el siguiente ejemplo de un archivo .csv con encabezados. 

FirstName,LastName,Address,City,State,PhoneNumber,Title,Level,Notes
Jorge,Souza,12345 Mills Rd,Anytown,SC,703-555-1234,CEO,10,
Paulo,Santos,0 Street,Anytown,MD,404-555-111,CIO,9,This is a really long note that could really be a paragraph
Mateo,Jackson,1 Two St,Anytown,NY,304-555-1324,COO,9,""
Terry,Whitlock4 N St,Anytown,VA,407-555-8888,EA,7,Secret notes
Diego,Ramirez,9 Hollows Rd,Anytown,VA,407-555-1222,SDE I,4,null
John,Doe,8 Hollows Rd,Anytown,VA,407-555-4321,SDE I,4,Jane's younger brother
Jane,Doe,8 Hollows Rd,Anytown,VA,407-555-4322,SDE II,5,John's older sister

En el siguiente ejemplo de esquema mapeado, las columnas FirstName y LastName son columnas cleartext. La columna State está cifrada como columna fingerprint y como columna sealed con un relleno de none. Las columnas restantes se omiten. 

{
  "headerRow": true,
  "columns": [
    {
      "sourceHeader": "FirstName",
      "targetHeader": "GivenName",
      "type": "cleartext"
    },
    {
      "sourceHeader": "LastName",
      "targetHeader": "Surname",
      "type": "cleartext"
    },
    {
      "sourceHeader": "State",
      "targetHeader": "State_Join",
      "type": "fingerprint"
    },
    {
      "sourceHeader": "State",
      "targetHeader": "State",
      "type": "sealed",
      "pad": {
        "type": "none"
      }
    }
  ]
}

El siguiente es el archivo .csv que resulta del esquema mapeado. 

givenname,surname,state_fingerprint,state
John,Doe,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:FQ3n3Ahv9BQQNWQGcugeHzHYzEZE1vapHa2Uu4SRgSAtZ3qObjPA4TcsHt+BOkMKBcnHWI13BeGG/SBqmj7vKpI=
Paulo,Santos,01:hmac:CHF4eIrtTNgAooU9v4h9Qjc+txBnMidQTjdjWuaDTTA=,01:enc:KZ5n5GtaXACco65AXk48BQO2durDNR2ULc4YxmMC8NaZZKKJiksU1IwFadAvV4iBQ1Bus5TU5c4biez3bilfTY8=
Mateo,Jackson,01:hmac:iIRnjfNBzryusIJ1w35lgNzeY1RQ1bSfq6PDHW8Xrbk=,01:enc:mLKpS5HIOSgphdEsrzhEdIp/eN9nBO2gAbIygt4OFn4LalYn9Xyj/XUWXlmn8zFe2T4kyDTD8kGOvpQEUGxAUFk=
Diego,Ramirez,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:rmZhT98Zm+IIGw1UTjMIJP4IrW/AAltBLMXcHvnYfRgmWP623VFQ6aUnhsb2MDqEw4G5Uwg5rKKZepUxx5uKbfk=
Jorge,Souza,01:hmac:3BxJdXiFFyZ8HBbYNqqEhBVqhNOd7s2ZiKUe7QiTyo8=,01:enc:vVaqWC1VRbhvkf8gnuR7q0zxVPcvEjuaglYz34+KyyLcGZLpAmsDUc6wZ07f2KvHoOySqRsEU7dG1QfdHYcTSWE=
Terry,Whitlock01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:3c9VEWbODO/xbQjdGuccLvI7oZTBdPU+SyrJIyr2kudfAxbuMQ2uRdU/q7rbgyJjxZS8M2U35ILJf/lDgTyg7cM=
Jane,Doe,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:9RWv46YLveykeNZ/G0NdlYFg+AVdOnu05hHyAYTQkPLHnyX+0/jbzD/g9ZT8GCgVE9aB5bV4ooJIXHGBVMXcjrQ=

Esquema de tabla posicional

El esquema posicional tiene la siguiente forma.

{
  "headerRow": false,
  "columns": [
    [
      {
        "targetHeader": STRING,
        "type": TYPE,
        "pad": PAD
      },
      {
        "targetHeader": STRING,
        "type": TYPE,
        "pad": PAD
      }
    ],
    [],
    ...
  ]
}

Si headerRow es false, es el siguiente campo del objeto es columns, que contiene una matriz de entradas. Cada entrada es en sí misma una matriz de cero o más esquemas de columnas posicionales (sin sourceHeader campo), que son JSON objetos que describen lo que debe contener la salida.

  • sourceHeader: el nombre del encabezado STRING de la columna de origen a partir de cual se derivan los datos.

    nota

    Este campo debe omitirse en los esquemas posicionales. En los esquemas posicionales, la columna de origen se deduce mediante el índice correspondiente de la columna en el archivo de esquema.

  • targetHeader: el nombre del encabezado STRING de la columna correspondiente del archivo de salida.

    nota

    Este campo es obligatorio para los esquemas posicionales.

  • type: el TYPE de la columna de destino del archivo de salida. Es decir, una de las columnas cleartext, sealed o fingerprint dependiendo de cómo se vaya a utilizar la columna en la colaboración.

  • pad: un campo de un objeto de esquema de columnas que solo está presente cuando TYPE es sealed. Su valor correspondiente de PAD es un objeto que describe cómo deben rellenarse los datos antes del cifrado.

    {
  "type": PAD_TYPE,
  "length": INT
}

    Para especificar el relleno previo al cifrado, se utiliza type y length de la siguiente manera:

    • PAD_TYPE como none: no se aplicará ningún relleno a los datos de la columna y el campo length no es aplicable (es decir, se omite).

    • PAD_TYPE como fixed: los datos de la columna se rellenan hasta el número de bytes especificado, length.

    • PAD_TYPE como max: los datos de la columna se rellenan hasta el tamaño de la longitud en bytes del valor más largo, más length bytes adicionales.

      nota

      fixed es útil si sabe con antelación cuál es el límite superior del tamaño en bytes de los datos de la columna. Se produce un error si algún dato de esa columna supera la length especificada.

      max resulta práctico cuando se desconoce el tamaño exacto de los datos de entrada, ya que funciona independientemente del tamaño de los datos. Sin embargo, max requiere un tiempo de procesamiento adicional porque cifra los datos dos veces. max cifra los datos una vez cuando se leen en el archivo temporal y una vez que se conoce la entrada de datos más larga de la columna.

      Además, la longitud del valor más largo no se guarda entre las invocaciones del cliente. Si tiene previsto cifrar los datos por lotes o cifrar datos nuevos periódicamente, tenga en cuenta que la longitud del texto cifrado resultante puede variar de un lote a otro.

A continuación se muestra un ejemplo de esquema posicional.

{
  "headerRow": false,
  "columns": [
    [
      {
        "targetHeader": "name",
        "type": "cleartext"
      }
    ],
    [
      {
        "targetHeader": "city_sealed",
        "type": "sealed",
        "pad": {
          "type": "max",
          "length": 16
        }
      }
    ],
    [
      {
        "targetHeader": "phone_number_fingerprint",
        "type": "fingerprint"
      },
      {
        "targetHeader": "phone_number_sealed",
        "type": "sealed",
        "pad": {
          "type": "fixed",
          "length": 20
        }
      }
    ]
  ]
}

Como ejemplo complejo, el siguiente es un ejemplo de un archivo .csv sin la primera fila con los encabezados. 

Jorge,Souza,12345 Mills Rd,Anytown,SC, 703 -555 -1234,CEO, 10,
Paulo,Santos, 0 Street,Anytown,MD, 404-555-111,CIO, 9,This is a really long note that could really be a paragraph
Mateo,Jackson, 1 Two St,Anytown,NY, 304-555-1324,COO, 9, ""
Terry,Whitlock, 4 N St,Anytown,VA, 407-555-8888,EA, 7,Secret notes
Diego,Ramirez, 9 Hollows Rd,Anytown,VA, 407-555-1222,SDE I, 4,null
John,Doe, 8 Hollows Rd,Anytown,VA, 407-555-4321,SDE I, 4,Jane's younger brother
Jane,Doe, 8 Hollows Rd,Anytown,VA, 407-555-4322,SDE II, 5,John's older sister

El esquema posicional tiene la siguiente forma. 

{
  "headerRow": false,
  "columns": [
    [
      {
        "targetHeader": "GivenName",
        "type": "cleartext"
      }
    ],
    [
      {
        "targetHeader": "Surname",
        "type": "cleartext"
      }
    ],
    [],
    [],
    [
      {
        "targetHeader": "State_Join",
        "type": "fingerprint"
      },
      {
        "targetHeader": "State",
        "type": "sealed",
        "pad": {
          "type": "none"
        }
      }
    ],
    [],
    [],
    [],
    []
  ]
}

El esquema anterior produce el siguiente archivo de salida con una fila de encabezados que contiene los encabezados de destino especificados. 

givenname,surname,state_fingerprint,state
Mateo,Jackson,01:hmac:iIRnjfNBzryusIJ1w35lgNzeY1RQ1bSfq6PDHW8Xrbk=,01:enc:ENS6QD3cMVl9vQEGfe9MNWfR0UOupchswZFr94zOMG5jY/Q8m/Y5SA89dJwKpT5rGPp8e36h6klwDoslpFzGvU0=
Jorge,Souza,01:hmac:3BxJdXiFFyZ8HBbYNqqEhBVqhNOd7s2ZiKUe7QiTyo8=,01:enc:LKo0zirq2++XEIIIMNRjAsGMdyWUDwYaum0B+IFP+rUf1BNeZDJjtFe1Z+zbZfXQWwJy52Rt7HqvAb2WIK1oMmk=
Paulo,Santos,01:hmac:CHF4eIrtTNgAooU9v4h9Qjc+txBnMidQTjdjWuaDTTA=,01:enc:MyQKyWxJ9kvK1xDQQtXlUNwv3F+yrBRr0xrUY/1BGg5KFgOn9pK+MZ7g+ZNqZEPcPz4lht1u0t/wbTaqzOCLXFQ=
Jane,Doe,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:Pd8sbITBfb0/ttUB4svVsgoYkDfnDvgkvxzeci0Yxq54rLSwccy1o3/B50C3cpkkn56dovCwzgmmPNwrmCmYtb4=
Terry,Whitlock01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:Qmtzu3B3GAXKh2KkRYTiEAaMopYedsSdF2e/ADUiBQ9kv2CxKPzWyYTD3ztmKPMka19dHre5VhUHNpO3O+j1AQ8=
Diego,Ramirez,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:ysdg+GHKdeZrS/geBIooOEPLHG68MsWpx1dh3xjb+fG5rmFmqUcJLNuuYBHhHAlxchM2WVeV1fmHkBX3mvZNvkc=
John,Doe,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:9uX0wZuO7kAPAx+Hf6uvQownkWqFSKtWS7gQIJSe5aXFquKWCK6yZN0X5Ea2N3bn03Uj1kh0agDWoiP9FRZGJA4=