Manual de usuario

Introducción

A la izquierda de la pantalla principal, puedes visualizar un panel con tres principales funcionalidades de Fynd:

Dashboards: lista los tableros creados
Queries: lista los consultas creadas
Alerts: lista los alertas creadas

A continuación tienes disponible el botón de “+ Create” mediante el cuál puedes crear un reporte, consulta o alerta.

Fynd Search Schema

El buscador de Schema en Fynd permite ver todos los datos disponibles que puedes usar en tus consultas o dashboards.
Seleccionando alguna de las tablas disponibles, puedes expandir y revelar todas sus columnas disponibles. Usando el campo de búsqueda, puedes encontrar las tablas y columnas que necesitas.

Crear consulta

Cualquier usuario con acceso a Fynd puede crear consultas utilizando el estándar ANSI-SQL. Es importante tener en cuenta que consultas más complejas pueden tomar más tiempo para completarse y mostrar los resultados.
Para crear una consulta, en el panel izquierdo debes posicionarte en "Create" y luego hacer click en "New Query".

En el editor puedes escribir la consulta deseada. En el siguiente ejemplo utilizamos la tabla de Cargos para obtener las Ventas y Transacciones diarias del producto de Tarjetas para un año en específico.

Para ejecutar una consulta y visualizar los resultados, debes hacer click en "Execute".

Puedes utilizar un parámetro que al momento de ejecutar la consulta puedes completar con el dato requerido, por ejemplo si quieres ejecutar la misma para distintos años puedes reemplazar el año por un parámetro. Para incorporar un parámetro debes hacer click en el siguiente botón:

A continuación, se desplegará una ventana donde debes completar:

Keyword: palabra clave que se visualiza en el texto de la consulta
Title: por defecto el título del parámetro corresponde al mismo que la palabra clave en el texto de la consulta. Si quieres darle un nombre más amigable, puedes cambiarlo aquí.
Type: tipo de dato del parámetro, los tipos disponibles son los siguientes Text, Number, Date, Date and Time, Date and Time (with seconds), Date Range, Date and Time Range, Date and Time Range (with seconds), Dropdown List y Query Based Dropdown List.

Una vez completado los datos necesarios, debes hacer click en “Add Parameter”.

A continuación automáticamente se creará el parámetro en tu consulta. En la misma puedes ver la Palabra clave definida entre dos corchetes y debajo del editor de consultas puedes encontrar el Título junto a un caja de texto donde debes escribir el valor que quieras visualizar.

Una vez colocado el año, simplemente debes hacer click en “Apply Changes” y la consulta retornará el resultado para el año indicado.

Guardar consulta

Para guardar una consulta, primero debes asignar un nombre haciendo click sobre el título "New Query". Luego hacer click en "Save". En el siguiente ejemplo, se guarda la consulta vista con el nombre "Transacciones".

Tienes la opción de incorporar una etiqueta a tu consulta de tal forma que luego te permita encontrarla de forma fácil y rápida. Para realizarlo debes hacer click en “+Add Tag”.

A continuación se despliega una ventana donde puedes seleccionar un Tag existente o escribir uno nuevo:

Si quieres colocar una nueva etiqueta, debes escribir el nombre. En el siguiente ejemplo incorporamos una etiqueta que indique que la consulta corresponde a un dato transaccional:

Finalmente, junto al nombre de la consulta puedes visualizar la etiqueta incorporada:

En la sección "Queries" puedes encontrar todas las queries guardadas seleccionando la opción "My Queries", así como también todas las queries guardadas y compartidas por todos los miembros del equipo de tu cuenta en la sección "All Queries".

Visualizar resultados

Luego de ejecutar la consulta debajo del editor se encuentra el visualizador de resultados donde puedes observar un máximo de 100.000 resultados. Cabe destacar que por default el límite establecido es de 1.000 resultados, para visualizar el límite máximo debes destildar la opción

Además, puedes ordenar los resultados haciendo click en la columna deseada. También puedes añadir un gráfico haciendo click en "Add Visualization".

Al hacer click en "Add Visualization", se despliega el Editor de visualización donde puedes crear gráficos. Entre los datos a completar puedes encontrar:

Visualization chart: tipo de gráfico a visualizar, las opciones disponibles son Chart (Line, Bar, Area, Pie, Scatter), Map, Cohort, Counter, Details View, Funnel, Pivot Table, Sankey, Sunburst Sequence, Table, Word Cloud
Visualization name: nombre de la visualización

Finalmente dependiendo el tipo de gráfico seleccionado se listan otros campos a completar. A continuación, se muestra un evolutivo de ventas diarias utilizando la visualización de Tipo Chart donde la gráfica utilizada es Line, en el "eje X" se lista la Fecha mientras que en el "eje Y" la Venta.

Para guardar la visualización se debe hacer click en "Save".

Puedes encontrar el gráfico creado en la solapa "Evolutivo de ventas" debajo del editor de consulta. Mientras que en la solapa “Table” tienes disponible el resultado de la consulta.

Programar consulta

Fynd permite configurar la actualización automática de tus consultas, las mismas se pueden programar de forma intradiaria, diaria, semanal o mensualmente. De esta manera puedes pre procesar la información que quieres ver para tenerla siempre disponible. Para hacerlo debes asegurarte previamente que tu consulta esté guardada haciendo click en “Save”, y luego debes seleccionar la opción "Never" en “Refresh Schedule” donde eliges la frecuencia de actualización deseada.

A continuación, se despliega la siguiente pantalla donde debes elegir la frecuencia.

Descargar resultados

Haciendo click en los tres puntos puedes descargar el resultado en un archivo con formato CSV, TSV o Excel.

Una vez que guardas la consulta se dispone el botón "Edit Visualization" donde puedes editar el formato de los campos. Por ejemplo cambiar la forma de visualización de una fecha de 01/01/2023 a 2023-10-01.

Al seleccionar la opción, se despliega el Editor de visualización donde puedes modificar el formato de las columnas creadas en la consulta.

Automatizar Consultas Mediante API

Ademas de poder descargar el resultado de una query de forma manual.
Fynd permite realizar llamadas a su API y obtener los resultados de forma automática.
Para poder utilizar esta función debes asegurarte que tu query se encuentre guardada.

Lo primero que necesitamos es obtener la API key de nuestro usuario, para esto haciendo click en tu perfil de Usuario, podemos entrar en la seccion Profile

En esta sección tendremos disponible nuestra API KEY personal, la cual podremos regenerar si es necesario

Lo segundo que necesitamos es el ID de nuestra query, podemos obtenerlo directamente desde la URL:
Por ejemplo en este caso: https://fynd.data.conekta.io/queries/697 el ID es 697

A continuación podemos observar un código de ejemplo necesario para conectarnos a Fynd, utilizar la API Key de nuestra query y obtener los resultados en un Dataframe de Pandas

Aclaración: Si nuestra query posee parámetros es necesario modificar la variable query_parameters para agregarlos junto con los valores que deseamos.

import json
import requests
import pandas as pd
import time

def execute_query(fynd_url, query_id, query_parameters, api_key):
    s = requests.Session()
    s.headers.update({'Authorization': 'Key {}'.format(api_key)})

    body = {
        "parameters": query_parameters
    }

    response = s.post('{}/api/queries/{}/results'.format(fynd_url, query_id), json=body)

    if response.status_code != 200:
        print(f"Error al ejecutar la consulta con ID {query_id}")
        return None

    if response.status_code == 200:
        if 'query_result' in response.json():
            json_result = response.json()['query_result']['data']['rows']
            df = pd.DataFrame(json_result)
            return df

        if 'job' in response.json():
            job = response.json()
            job_id = job['job']['id']

            # Monitorear el estado del trabajo hasta que esté completo
            while True:
                job_response = s.get("{}/api/jobs/{}".format(fynd_url, job_id))
                job_status = job_response.json()['job']['status']

                if job_status in (3, 4):  # 3: success, 4: error
                    break
                else:
                    time.sleep(1)

            if job_status == 3:
                print(f"La consulta con ID {query_id} se ha ejecutado y actualizado correctamente.")
                query_result_id = job_response.json()['job']['query_result_id']
                query_result_response = s.get(f"{fynd_url}/api/query_results/{query_result_id}")
                query_result = query_result_response.json()
                return query_result['query_result']['data']['rows']
            else:
                print(f"Error al ejecutar la consulta con ID {query_id}")
                return None

fynd_url = 'https://fynd.data.conekta.io'
query_parameters = {}# Completar de ser necesario. Por ejemplo: {'fecha_desde': '2023-01-01', 'fecha_hasta': '2023-01-02'}
query_id = [QUERY ID ]# Completar
api_key = 'NUESTRA API KEY'# Completar

resultado = execute_query(fynd_url, query_id, query_parameters, api_key)

Compartir conocimiento

Para compartir una consulta con el resto del equipo en tu cuenta, primero debes publicarla haciendo click en el botón “Publish”.

Toda consulta publicada será accesible para todos los miembros de la cuenta en la sección "Queries" opción "All Queries".
Por defecto, toda consulta compartida se encuentra en modo solo lectura, por lo que otros miembros no podrán modificar las consultas que creaste.

Crear Alerta

En Fynd tienes la opción de crear y configurar alertas. Una alerta te permite recibir una notificación por email cuando el valor deseado se encuentra por debajo, por encima o es igual a cierto valor. Antes de configurar una alerta, es muy importante que crees tu consulta y programes su actualización. Esto lo realizas dentro de la consulta, en la esquina inferior izquierda donde dice “Refresh Schedule“.

Una vez hecho esto, en el panel izquierdo debes posicionarte en "+Create" y luego hacer click en "New Alert".

Primero seleccionas la consulta sobre la cual deseas crear la alerta e ingresas el nombre deseado.
A continuación, en "Trigger when" indicas la condición que debe ocurrir para que la alerta genere la notificación a tu correo.
En "Value column" seleccionas el campo “Target” a evaluar, en "Condition" cuál condición debe cumplir y en "Threshold" el valor de referencia a utilizar en la condición.
La opción “When triggered, send notification” permite seleccionar 3 formas en las cuales la alerta puede notificarte.

Just Once: se recibe una notificación solamente si su estado cambia. Mientras el estado se mantenga igual no se reciben notificaciones.
Each Time: se recibe una notificación cada vez que la consulta se actualiza según la programación seteada y el estado de la alerta sea Triggered.
At most every: permite agregar un intervalo mínimo entre notificaciones, lo que permite funcionar a la alerta de forma similar a Each Time pero evitando recibir notificaciones cada vez que la alerta se ejecute y el estado sea Triggered.
Una vez completado todos los campos, debes hacer click en “Create Alert”.
En el siguiente ejemplo se visualiza la creación de una alerta en caso de que la cantidad de ventas diarias sea menor a 10.000.

Una alerta puede tener tres estados diferentes:

TRIGGERED: significa que el valor de la columna Target según la última ejecución alcanzó la condición definida. Por ejemplo: si la alerta chequea que el campo Ventas sea menor al valor 10.000 entonces, la alerta estará en estado Triggered cuando las ventas sean menor a 10.000.
OK: significa que el valor Target en la última ejecución de la consulta no cumplió con la condición definida.
UNKNOWN: cuando Fynd no cuente con información suficiente para evaluar la condición, la alerta se encontrará en estado Unknown. Esto puede pasar, por ejemplo, cuando se crea la alerta hasta que se ejecute por primera vez la consulta o cuando la consulta no cuenta con la columna Target.

En la sección "Alerts" puedes encontrar todas las alertas creadas.

Crear reporte

Para crear un reporte, en el panel izquierdo debes posicionarte en "+Create" y luego hacer click en "New Dashboard".
Es importante destacar que para la creación de un nuevo reporte, las consultas que lo componen deben estar previamente creadas con sus correspondientes visualizaciones. Un reporte puede estar compuesto por una o más consultas, no es necesario que los gráficos se basen en un solo origen.

A continuación debes completar con el nombre a asignarle a tu nuevo reporte y luego hacer click en "Save".

Finalmente se despliega el Editor del reporte.

En el panel debajo del editor puedes visualizar dos opciones:

Add Text Box: permite incorporar al reporte un cuadro de texto
Add Widget: permite incorporar la visualización de una consulta, cabe mencionar que es necesario tener la consulta creada previamente junto a su visualización

A continuación, detallaremos cómo crear cada opción:

Crear Text Box

Luego de hacer click en “Add Text Box” se despliega una pantalla donde debes completar el texto a incorporar al reporte. En el siguiente ejemplo, detallamos que indicadores muestra el reporte.

Luego de hacer click en “Add to Dashboard”, se crea el cuadro de texto en tu reporte.

Puedes editar la posición del cuadro simplemente haciendo click en él y arrastrándolo a donde quieras colocarlo, también puedes editar su tamaño haciendo click en el siguiente icono:

Crear Widget

Luego de hacer click en “Add Widget” se despliega una ventana donde debes seleccionar qué consulta utilizarás para crear el Widget.

En caso de no ver la consulta que quieres seleccionar, puedes escribir el nombre de la misma y se filtran todos las consultas con ese nombre.

Una vez que selecciones la consulta, en una nueva ventana puedes se listan las visualizaciones que contiene la consulta y sus parámetros.

Inicialmente debes hacer click en “Choose Visualization”, donde se desplegarán todas las opciones de visualizaciones que contenga la consulta seleccionada. Debes elegir qué visualización deseas colocar en tu reporte.
En el siguiente ejemplo, para la consulta “Transacciones” encontramos la visualización “Table”, que lista el resultado de la consulta, y un gráfico de tipo “Chart”.

Para el caso mencionado seleccionamos el gráfico Evolutivo ventas.

En la siguiente sección puedes visualizar el listado de parámetros que contiene la consulta seleccionada. Puedes eliminar o mantener los parámetros que desees. En nuestro ejemplo, mantendremos el parámetro de Año.

Finalmente para incorporar el Widget al reporte, debes hacer click en “Add to Dashboard”.

A continuación se incorporará a tu reporte, el Widget creado y en el panel superior de tu reporte puedes ver los parámetros elegidos. Cabe destacar que si al parámetro no se le coloca un valor el reporte mostrará un mensaje de error tal como se muestra a continuación.

A continuación, incorpora todos los gráficos necesarios en tu reporte y una vez que termines de editarlo debes hacer click en “Done editing”.

Finalmente publica tu reporte para que pueda ser compartido con tu equipo.

En la sección "Dashboards" puedes encontrar todos los reportes guardados seleccionando la opción "My Dashboards", así como también todas los reportes guardados y compartidos por todos los miembros del equipo de tu cuenta en la sección "All Dashboards".

Editar reporte

Para editar un reporte creado, debes ingresar al reporte y seleccionar la opción “Edit” encontrada en el siguiente icono disponible en la esquina superior del panel.

A continuación realiza las modificaciones necesarias en tu reporte y realiza click en “Done editing”.

Conversión de zona horaria

Mediante la función convert_timezone puedes modificar las fechas de UTC (zona horaria predeterminada) a otra zona horaria específica. La función consta de 3 parámetros:

CONVERT_TIMEZONE ( ['source_timezone',] 'target_timezone', 'field_timestamp')

source_timezone: zona horaria predeterminada UTC
target_timezone: zona horaria a convertir
field_timestamp: campo a modificar zona horaria

Puedes ejecutar la siguiente consulta en Fynd para obtener el listado completa de las zonas horarias disponibles:

select pg_timezone_names();

La consulta retornará 3 valores separados por una coma, la zona horaria corresponde al primer valor informado.

Por ejemplo, si te encuentras en México, y quieres convertir la fecha de tus cargos a la zona horaria de Ciudad de México, la consulta debe ser de la siguiente forma:

CONVERT_TIMEZONE ('America/Mexico_City', created_dttm) as fecha_mx