En el siguiente tutorial se va a explicar cómo utilizar la herramienta de DataFlow para cargar un archivo GeoJSON de geometrías variadas (polígonos y multipolígonos) en una ontología de Plataforma para su posterior consumo (ya sea en un visor cartográfico, para serviciarlo en un API REST, etc.).

1.- Los datos

Para llevar a cabo este tutorial, se va a utilizar un GeoJSON con los polígonos simplificados de las Comunidades Autónomas de España situadas en la Península Ibérica (y norte de África), el cual está basado en este TopoJSON en concreto, el cual ha sido preparado y subido a Plataforma en el siguiente Binary File.

Como esto es un ejemplo, el GeoJSON con el que se trabaja es pequeño, pero lo normal es que dichos archivos contengan grandes volúmenes de datos; imaginemos los municipios de España (8131 polígonos a 2019), o las secciones censales de una Comunidad Autónoma (4272 polígonos sólo para la Comunidad de Madrid, con un peso de 17 megas).

Es por ello que se recomienda hacer un pequeño procesado previo a la ingesta por parte de DataFlow: para optimizar la carga y velocidad de procesado, se van a extraer los features del GeoJSON, omitiendo por tanto la cabecera del FeatureCollection y quedándonos únicamente con lo que hay dentro de los corchetes.

Es decir, el procesado consiste en generar un documento en el que cada línea contiene uno de los features del FeatureCollection, como se puede apreciar a continuación:

Open

Para facilitar la elaboración del tutorial y agilizar el proceso, se ha preparado y subido a este Binary File el GeoJSON preprocesado (ahora JSON, tras la pérdida de los atributos de FeatureCollection).

2.- Creación de la ontología

Seguidamente, hay que crear la ontología en donde se quiere importar el GeoJSON. Esto se hará (desde un usuario de tipo Analytics) desde el menú lateral de Analytics Tools > My Ontologies.

Open

De entre las diferentes opciones que aparece, se seleccionará la opción de creación paso a paso:

Para este tutorial, se ha creado una ontología con la siguiente información (si estáis creando vuestro propio ejemplo, recordar en cambiar el nombre de la ontología u os dará un error de duplicación de nombres):

• NAME: tutorial_geojson.

• META-INFORMATION: geojson, tutorial.

• ACTIVE: casilla marcada.

• PUBLIC: casilla marcada.

• DESCRIPTION: Esta ontología se usa en el tutorial de carga de GeoJSON con DataFlow.

• ALLOW ENCRYPTION OF FIELDS: casilla desmarcada.

A continuación hay que definir el esquema de la ontología. Para esta ontología en concreto, no sirven los esquemas preexistentes (de momento) ya que si bien es cierto que se contemplan esquemas con geometrías espaciales, los esquemas están pensados para contener un único tipo de geometría, mientras que para este ejemplo se quiere usar multigeometría (polígonos y multipolígonos). Por ello, se cargará un esquema de ontología personalizado que soporte todos los tipos de geometrías.

Para ello, se navegarça hasta la pestaña de generación de esquemas e instancias de JSON.

Se seleccionará la opción de mostrar el texto del esquema:

En la ventana, se tendrá que cargará la plantilla de esquema de GeoJSON, que podéis descargar desde este Binary File.

Una vez introducido el esquema de ontología, se creará la ontología pulsando en el botón de New, situado en la parte inferior de la pantalla.

3.- Procesado en DataFlow

3.1.- Crear el Digital Client

En primer lugar, hay que crear el Digital Client que gestionará el pipeline del DataFlow. Para ello, hay que acceder al menú lateral de Digital Clients > My Digital Clients.

Una vez que se acceda al gestor de clientes digitales, hay que generar uno nuevo pulsando en el botón de Create, situado en la parte superior derecha de la pantalla.

En el creador del cliente digital, se rellenarán los siguientes campos (recordad en cambiar el nombre del cliente digital si estáis replicando el tutorial):

• IDENTIFICATION: dc_tutorial_geojson.

• DESCRIPTION: Cliente digital del tutorial de GeoJSON con DFlow.

• ONTOLOGIES: hay que seleccionar la ontología de destino (en este caso, ‘tutorial_geojson’).

• ACCESS LEVEL: el acceso de lectura/escritura que se le da para la ontología; hay que selecionar ‘ALL’.

• ONTOLOGIES: el listado de ontologías autorizadas. Cuando se pulsa en ‘ADD ONTOLOGY’, se añade al listado la ontología seleccionada.

Debajo del listado de ontologías, aparece un TOKEN, que habrá que guardar para su uso posterior.

3.2.- Crear nuevo DataFlow

Seguidamente, se va a proceder a crear el DataFlow en si. Para ello, hay que acceder al menú lateral de Analytics Tools > My DataFlows.

Desde el gestor de DataFlows, se pinchará en el botón de Nuevo DataFlow, situado en la parte superior derecha de la pantalla.

Esto abrirá un modal que solicitará el nombre del Pipeline a crear y su tipo. Para el tutorial se ha introducido la siguiente información:

Tras pulsar el botón de OK, se abrirá el editor del Pipeline del DataFlow.

3.3.- Crear el Pipeline

El modelo más sencillo incluye una entrada y una salida; en este caso, la entrada será el GeoJSON preprocesado que se ha preparado, y la salida la ontología creada previamente.

Para incluir la entrada, se seleccionará la caja de HTTP Client desde el menú lateral derecho, justo a la derecha del botón verde de Start, y se arrastrará a la mesa de trabajo cuadriculada.

Inicialmente saldrá un símbolo de exclamación en el módulo cargado. Esto se debe a que no se encuentra configurado y le faltan datos, por lo que salta un error. Seleccionando la caja en la mesa de trabajo, aparecerá en la parte inferior el configurador del módulo.

La primera pestaña a configurar será la de General. Aquí no hay que hacer obligatoriamente nada, pero se le puede asignar un nombre al módulo. En este caso en particular se le ha dado el nombre de ‘GeoJSON source’:

La siguiente pestaña a configurar es la de HTTP, en donde se indicará la localización de los datos y su modo de carga.

• Resource URL: aquí se introducirá la URL del GeoJSON preprocesado.

• Mode: Batch (para realizar una única carga).

La siguiente pestaña a configurar es la de Data Format, en donde habrá que asegurarse que el formato de datos es de tipo JSON, y que la longitud máxima del objeto tenga un valor alto, pues ya que el sistema está leyendo línea por línea (el JSON no se considera formateado) el valor por defecto se queda corto.

• Data Format: JSON

• Max Object Length (chars): 524288 (o superior si es necesario)

El resto de pestañas no son necesarias configurarlas para este tutorial, por lo que se pueden omitir.

Para configurar la salida, se arrastrará a la mesa de trabajo otra caja del menú lateral, con nombre onesaitPlatform Destination.

Al igual que la caja anterior, presentará un icono de exclamación indicando que algo falla. Seleccionando el módulo, se procederá a configurarla.

Como en el caso anterior, la primera pestaña corresponde a General, pudiendo cambiar el nombre y algunas de sus propiedades genéricas. Para este ejemplo, se le pondrá como nombre de módulo ‘Ontology’.

La siguiente pestaña a configurar es la de Source, en donde habrá que actualizar algunas de las propiedades que vienen por defecto (sólo se comentan las que hay que cambiar).

• Token: la clave generada en la creación del cliente digital (y que se dijo que había que guardar).

• IoTClient: el identificador del cliente digital; en este caso: ‘dc_tutorial_geojson’.

• IoTClient ID: el nombre que se le quiere dar en este Pipeline; puede ponerse lo que sea. En este caso se ha escogido el nombre del IoTClient con un número al final.

• Ontology: el nombre de la ontología de destino, añadida previamente al cliente digital; en este tutorial es ‘tutorial_geojson’.

• Root node type: hay que cambiarlo a ‘Custom root node'.

• Custom root node name: el nombre de la raíz de la ontología, definido en la plantilla, que en caso de la de GeoJSON es ‘geojson_template’.

Hecho esto, la salida ha quedado configurada (no hace falta tocar el resto de pestañas).

A continuación, hay que unir ambas cajas uniéndolas por los puntos que tienen lateralmente.

Por último, se tiene que pinchar sobre la mesa de trabajo, y acceder a la pestaña de Error Records, en donde se configurará la gestión de errores tal como se especifica a continuación:

• Error Records: Discard (Library: Basic)

3.4.- Probar el Pipeline

Terminado el flujo del Pipeline, se va a probar que funciona correctamente. Para ello, se pulsará en primer lugar en el botón de Validate, situado a la izquierda del botón de Start, para comprobar que todas las conexiones son correctas.

Si la validación es correcta, aparecerá un mensaje sobre la mesa de trabajo indicando que la validación se ha llevado a cabo correctamente.

A continuación, se pulsará sobre el botón de Preview, situado a la izquierda del botón de validación usado previamente.

Esto lanzará un modal con la configuración de la previsualización, donde se tendrá que configurar tal como se ve a continuación:

Tras lanzar la previsualización, si todo ha ido correctamente se mostrará bajo la mesa de trabajo lo que sale de la caja de entrada, y lo que recibe la caja de salida.

Por último, se puede hacer una ingesta de prueba en la ontología, para no tener que cargar todo el contenido si no entra como interesa. Para ello, hay que parar la previsualización y volver a lanzarla, pero modificando un poco las propiedades del modal que aparece tal como se indica a continuación:

• Preview Batch Size: 1 (o cualquier número bajo, pues serán los registros a ingestar).

• Write to Destinations and Executors: activado, para que ingeste el dato en el destino.

Tras lanzar la previsualización, y si todo ha ido correctamente, se comprobará que efectivamente la ontología a ingestado el dato tal como se quiere. Para ello, habrá que ir al menú lateral de Tools > Query Tool.

Desde la herramienta de consultas se seleccionará la base de datos en la que se ha ingestado el dato de prueba, que en este caso es tutorial_geojson, y se lanzará la consulta para que muestre todos sus registros (en donde debería de mostrar un único registro, o tantos como se haya indicado en el configurador del previsualizador).

La consulta debería devolver el dato ingestado tal como se veía desde la ventana de previsualización del DataFlow.

Si la ingesta es correcta, se puede proceder a borrar el registro de prueba (desde el gestor de ontologías), y proceder a lanzar el Pipeline. Para ello, se cancelará la previsualización pulsando en el mismo botón de antes, y se pulsará en el botón de Start >Start Pipeline.

El DataFlow empezará a funcionar, y pasados unos momentos (dependiendo del tamaño del archivo de origen, por supuesto) la ingesta se habrá completado, algo que se denotará con otro mensaje sobre la mesa de trabajo.

Acudiendo nuevamente al Query Tool y lanzando la consulta, ahora la ontología debería de aparecer con todos los registros ingestados (16, en el caso del ejemplo propuesto).

Con esto damos por terminado el tutorial. Cualquier duda o problema que os surja, por favor dejadnos un comentario por aquí y lo revisaremos cuanto antes.