Este documento incluye algunas de las preguntas técnicas frecuentes sobre Canvas Data 2 (CD2).
¿Qué significa la marca de tiempo 'ts' en el campo 'meta' del conjunto de resultados de la consulta?
ts es la marca de tiempo de la última modificación (o fecha de confirmación) del registro en la tabla. Cuando se inserta un nuevo registro en una tabla alojada en CD2, se le asigna la fecha de inserción. Cuando ese registro se actualiza posteriormente, la marca de tiempo se actualiza para que coincida con la fecha de la actualización. Finalmente, cuando el registro se elimina, la marca de tiempo refleja la fecha de eliminación.
¿Cómo se relacionan 'since' y 'until' con 'ts' en el conjunto de resultados?
since y until son filtros basados en la fecha de confirmación (o la marca de tiempo de la última modificación). Todos los registros del conjunto de resultados están dentro del rango since y until .
¿Puedo obtener registros duplicados de la misma clave en el conjunto de resultados?
No; las claves en el conjunto de resultados de una instantánea o una consulta incremental siempre son únicas.
¿Cómo convierto un conjunto de resultados de una consulta incremental en una declaración SQL?
Probablemente quieras usar una instrucción INSERT o UPDATE. En PostgreSQL, esto se ve así:
INSERT INTO ... (...)
VALUES (...)
ON CONFLICT (...)
DO UPDATE SET ...
¿Qué hago con los registros en el conjunto de resultados que tienen una 'clave' pero ningún 'valor'?
Los registros de salida que tienen un campo key pero ningún campo value corresponden a registros eliminados. Los datos ya no están disponibles en los sistemas de Instructure y también deben eliminarse de su copia local. Estos registros también se marcan con la acción D en metadatos.
¿Qué significa '__cd2_oversized_truncated__'? (Algunos campos/columnas pueden tener este valor).
__cd2_oversized_truncated__ es un marcador de posición especial (constante de cadena) que indica que los datos originales eran demasiado grandes para incluirlos en el resultado, generalmente de varios MB. Lamentablemente, no es posible recuperar el valor de estos campos/columnas. Sin embargo, estos valores tan grandes suelen deberse a un error (por ejemplo, un estudiante que copia un documento binario de Word en un campo de texto sin formato) y rara vez contienen información valiosa para el análisis.
¿Cómo puedo capturar el estado de la base de datos en un momento determinado?
CD2 no admite consultas en un punto en el tiempo, no puede reconstruir un estado histórico anterior de la base de datos, solo puede sincronizar su copia local con el estado más actualizado que mantiene Instructure.
¿Cómo puedo obtener todos los datos desde el principio de los tiempos hasta una fecha específica?
Lamentablemente, CD2 no es compatible con esta función. CD2 permite sincronizar la base de datos local con el estado actual de la base de datos en Instructure. Si se ha actualizado o eliminado un registro en la base de datos de origen del dominio de Instructure, no se pueden recuperar las versiones anteriores. Sin embargo, los registros están disponibles indefinidamente mientras existan en los sistemas de Instructure; no se pierden con el tiempo. Por ejemplo, debería poder obtener todos los cursos a los que un estudiante se ha postulado o todas las tareas que ha entregado, ya que aparecen como registros diferentes, no como versiones del mismo registro.
¿Cómo puedo obtener un flujo de todas las transiciones de registros?
CD2 permite actualizar la base de datos al estado más reciente, pero no devuelve estados provisionales de forma fiable. Incluso si se intenta sondear el punto final del trabajo de consulta de la API de CD2 con un intervalo corto, varios eventos de captura de datos de cambio en el mismo registro se fusionarán en un solo cambio, y solo ese cambio se devolverá en el conjunto de resultados de la consulta incremental. La salida de CD2 no puede servir como registro de cambios de todas las transiciones de la base de datos, sino solo como un medio para actualizar la base de datos local con el estado más reciente de los sistemas de Instructure.
Solución de problemas
Recibí un código de estado HTTP 4xx como respuesta.
Un error de clase HTTP 4xx (p. ej., HTTP 400 Solicitud incorrecta) es un error permanente. Para saber más sobre el motivo del rechazo de su solicitud, consulte la carga útil de la respuesta HTTP. El cuerpo HTTP debe ser un tipo de medio application/json y contener un objeto con la propiedad error . Esto incluye información sobre el motivo del rechazo de la solicitud.
Las consultas incrementales tienen el campo action en meta , que especifica si un registro se insertó o actualizó (upserted) o se eliminó . Si se inserta un registro, normalmente se usaría una instrucción SQL INSERT o UPDATE en la base de datos para actualizarlo. Si se elimina un registro, se usaría la instrucción SQL DELETE para eliminarlo.
Las consultas de instantáneas no tienen action porque serían un campo redundante. Estas consultas asumen que la base de datos está vacía y que se deben insertar todos los registros. Normalmente, se usaría una instrucción COPY o INSERT para rellenar la base de datos.
La salida CSV en CD2 cumple con la RFC 4180. La sección 2.6 de esta especificación, que describe cómo se representan los saltos de línea en los valores, suele estar mal implementada en las herramientas. En concreto, si un valor tiene un salto de línea incrustado, la salida debe ir entre comillas dobles, pero el salto de línea debe representarse textualmente (no como una secuencia de escape). Sin embargo, las herramientas suelen asumir que un registro siempre cabe en una sola línea, lo cual no es el caso en estas circunstancias.
El script de creación de muestra de PostgreSQL tiene 'CREATE TYPE ... AS (...)' pero mi almacén de datos o motor de base de datos no admite esta sintaxis.
El script de referencia de PostgreSQL para crear la base de datos utiliza los llamados tipos anidados. No todos los motores de bases de datos los admiten. Si su motor no los admite, puede usar el tipo SQL más genérico json. json permite insertar estructuras anidadas arbitrarias como datos JSON. Sin embargo, es posible que no pueda filtrar las columnas json con la misma eficacia que otros tipos de columna.
Recibo un error que indica que no hay datos disponibles para el rango o que el rango está fuera de los límites.
Asegúrese de encadenar correctamente sus consultas incrementales. Siempre debe usar la marca de tiempo " hasta " de la consulta incremental anterior (o la marca de tiempo " at " de su consulta de instantánea inicial) como marca de tiempo " desde" de la siguiente consulta incremental. No debe especificar valores arbitrarios para estos parámetros; solo reutilice los devueltos por una respuesta anterior.
Parece que no puedo proporcionar una marca de tiempo "hasta" a menos que también proporcione una marca de tiempo "desde".
Las marcas de tiempo " desde" y "hasta" permiten encadenar consultas incrementales. Siempre debe usar la marca de tiempo " hasta" de la consulta incremental anterior como marca de tiempo " desde" de la siguiente consulta incremental. CD2 solo almacena el estado más reciente de cualquier registro; " hasta" no puede usarse para reconstruir el estado de un registro en un momento anterior.
Faltan algunos números de partes o secuencias en el conjunto de archivos devueltos por la API CD2.
La API CD2 puede devolver objetos S3 sin números de secuencia contiguos; por ejemplo, part1 , part2 y part5 podrían estar presentes, mientras que part3 y part4 podrían faltar. Esto no es un error.
Los nombres de archivo, en general, son informativos. No se deben hacer suposiciones basándose en el patrón del nombre de archivo.
Los archivos que devuelve la API CD2 se generan mediante la ejecución independiente de tareas concurrentes. Según el contexto de ejecución, los parámetros de entrada, etc., una tarea puede encontrar varios registros que coincidan con la consulta o no encontrar ninguno. Además, una tarea puede finalizar mientras procesa registros y su carga de trabajo puede delegarse a otra tarea. Por lo tanto, los números pueden no ser contiguos, lo que explica por qué podría tener part1 y part5 , pero no part4 .
Cada archivo de salida generado por la API CD2 puede contener cero o más registros. Un script de integración debería ser capaz de gestionar el caso en que el archivo no contenga registros.
Los archivos que devuelve la API CD2 se generan mediante la ejecución independiente de tareas concurrentes. Según el contexto de ejecución, los parámetros de entrada, etc., una tarea puede encontrar varios registros que coincidan con la consulta, o puede no encontrar ninguno. Si no se encuentra ningún registro, se devuelve un archivo vacío.
Los archivos vacíos son manejados automáticamente por la biblioteca cliente oficial CD2 .