Roman Klimenko
EN

Søgning efter entiteter med CluedIn Python SDK

cluedinpython

I den seneste version af CluedIn Python SDK forbedrede jeg understøttelsen af GraphQL Search API. Derfor er det et godt tidspunkt at vise, hvordan du henter entities, eller golden records, direkte med GraphQL og gennem SDK'et, som bruger det samme API.

Vi starter med GraphQL-playgrounden i CluedIn UI og slutter med en Python-query på én linje.

GraphQL Search API

GraphQL understøtter de fleste interaktioner med CluedIn. Ingestion endpoints er en af de få undtagelser. Den officielle dokumentation har en god introduktion til CluedIn GraphQL API.

Åbn Consume-sektionen i din CluedIn-instans for at finde en playground, hvor du kan køre GraphQL-queries.

Min instans indeholder nogle /Duck-entities fra DuckTales. Jeg kan finde dem med denne query:

{
  search(query:"+entityType:/Duck")
  {
    entries {
      id
      name
      entityType
    }
  }
}

Queryen returnerer de første 20 /Duck-entities. Parameteren query filtrerer svaret efter entity type, mens entries-blokken vælger de properties, der skal med i svaret: id, name og entityType.

Skift derefter queryen, så den modtager GraphQL-variabler:

query ($query: String, $pageSize: Int) {
  search(
    query: $query
    pageSize: $pageSize
    sort: FIELDS
    sortFields: {field: "id", direction: ASCENDING}
  ) {
    cursor
    entries {
      id
      name
      entityType
    }
  }
}

Variabler:

{
  "query": "+entityType:/Duck",
  "pageSize": 10000
}

Nogle dele af queryen er værd at bemærke:

  • query ($query: String, $pageSize: Int) definerer parametrene. Du kan også give queryen et navn: query searchEntities($query: String, $pageSize: Int).
  • sort: FIELDS sortFields: {field: "id", direction: ASCENDING} sorterer efter et unikt felt, så pagination bliver forudsigelig.
  • cursor beder CluedIn om den værdi, der skal bruges til at hente næste side.
  • "pageSize": 10000 hæver standardstørrelsen fra 20 til maksimum på 10.000. Brug en mindre værdi, når du kun skal bruge få entities, så queryen bliver hurtigere.
GraphQL

CluedIn Python SDK

Alle programmeringssprog kan sende en GraphQL-request til CluedIn. Her er fremgangsmåden i Python.

Installer den nyeste version af CluedIn Python SDK:

%pip install cluedin

Importer SDK'et sammen med Pandas, som vi bruger til at indlæse resultaterne i DataFrames:

import pandas as pd
import cluedin

Du skal også bruge et API-token. Kopiér eller opret et under Administration > API Tokens i CluedIn.

Min CluedIn-instans er installeret på https://foobar.klimenko.dk/. For at oprette en context angiver jeg organisationens navn (foobar), domænet (klimenko.dk) og det access token, jeg kopierede fra CluedIn UI:

ctx = cluedin.Context.from_dict({
    'domain': 'klimenko.dk',
    'org_name': 'foobar',
    'access_token': '{paste_your_token_here}'
})

Nu kan vi køre den tidligere GraphQL-query fra Python:

query = """
query searchEntities($query: String, $pageSize: Int) {
  search(
    query: $query
    pageSize: $pageSize
    sort: FIELDS,
    sortFields: {field: "id", direction: ASCENDING}
  ) {
    cursor
    entries {
      id
      name
      entityType
    }
  }
}
"""

variables = {
    'query': '+entityType:/Duck',
    'pageSize': 3
}

cluedin.gql.gql(ctx, query=query, variables=variables)

Resultatet indeholder de første tre entities, fordi eksemplet bruger en sidestørrelse på tre. Det indeholder også den cursor, der skal bruges til at hente næste side:

{'data': {'search': {'cursor': 'ewAiAFAAYQBnAGUAIgA6ADEALAAiAFAAYQBnAGUAUwBpAHoAZQAiADoAMwAsACIAQwBvAG0AcABvAHMAaQB0AGUAQQBmAHQAZQByACIAOgB7AH0ALAAiAFMAZQBhAHIAYwBoAEEAZgB0AGUAcgAiADoAWwAiADYAMwA1ADMAOAAzAGEAOQAtADkAYwA3ADUALQA1AGQANgAxAC0AOABmADIAYgAtAGYAZQA0ADkANgBmAGQAOAAyAGIAZQA3ACIALAAiADYAMwA1ADMAOAAzAGEAOQAtADkAYwA3ADUALQA1AGQANgAxAC0AOABmADIAYgAtAGYAZQA0ADkANgBmAGQAOAAyAGIAZQA3ACIAXQB9AA==',
   'entries': [{'id': '145afb55-4e78-5dad-b208-633b5b6d19cf',
     'name': 'Donald Duck',
     'entityType': '/Duck'},
    {'id': '17bad60e-6782-5ae5-84bf-7efe05e78e58',
     'name': 'Jake McDuck',
     'entityType': '/Duck'},
    {'id': '635383a9-9c75-5d61-8f2b-fe496fd82be7',
     'name': 'Dewey Duck',
     'entityType': '/Duck'}]}}}

Send denne cursor som parameter i næste request:

query = """
query searchEntities($cursor: PagingCursor, $query: String, $pageSize: Int) {
  search(
    query: $query
    cursor: $cursor
    pageSize: $pageSize
    sort: FIELDS,
    sortFields: {field: "id", direction: ASCENDING}
  ) {
    cursor
    entries {
      id
      name
      entityType
    }
  }
}
"""

variables = {
    'query': '+entityType:/Duck',
    'pageSize': 3
    'cursor': 'ewAiAFAAYQBnAGUAIgA6ADEALAAiAFAAYQBnAGUAUwBpAHoAZQAiADoAMwAsACIAQwBvAG0AcABvAHMAaQB0AGUAQQBmAHQAZQByACIAOgB7AH0ALAAiAFMAZQBhAHIAYwBoAEEAZgB0AGUAcgAiADoAWwAiADYAMwA1ADMAOAAzAGEAOQAtADkAYwA3ADUALQA1AGQANgAxAC0AOABmADIAYgAtAGYAZQA0ADkANgBmAGQAOAAyAGIAZQA3ACIALAAiADYAMwA1ADMAOAAzAGEAOQAtADkAYwA3ADUALQA1AGQANgAxAC0AOABmADIAYgAtAGYAZQA0ADkANgBmAGQAOAAyAGIAZQA3ACIAXQB9AA=='
}

cluedin.gql.gql(ctx, query=query, variables=variables)

Resultatet er de næste tre entiteter:

{'data': {'search': {'cursor': 'ewAiAFAAYQBnAGUAIgA6ADIALAAiAFAAYQBnAGUAUwBpAHoAZQAiADoAMwAsACIAQwBvAG0AcABvAHMAaQB0AGUAQQBmAHQAZQByACIAOgB7AH0ALAAiAFMAZQBhAHIAYwBoAEEAZgB0AGUAcgAiADoAWwAiADkAMwBiADkAMgA4ADMANQAtADkANgBmADIALQA1ADYAYQA5AC0AOQA4AGMAMAAtAGMAOAA0ADgAMgAzADYANQAyADEAYQA5ACIALAAiADkAMwBiADkAMgA4ADMANQAtADkANgBmADIALQA1ADYAYQA5AC0AOQA4AGMAMAAtAGMAOAA0ADgAMgAzADYANQAyADEAYQA5ACIAXQB9AA==',
   'entries': [{'id': '6ae43a44-81b4-5fd7-9c7b-47cb24d407ea',
     'name': 'Angus McDuck',
     'entityType': '/Duck'},
    {'id': '9353b703-13d8-59a1-886c-f40b95283c06',
     'name': 'Hortense McDuck',
     'entityType': '/Duck'},
    {'id': '93b92835-96f2-56a9-98c0-c848236521a9',
     'name': 'Matilda McDuck',
     'entityType': '/Duck'}]}}}

Du forstår ideen.

Brug cluedin.gql.entries, hvis du vil undgå at sende hver cursor manuelt. Metoden returnerer en generator, som du kan iterere direkte over eller konvertere til en liste:

...

# her skal du bruge en mindre sidestørrelse
# hvis du ikke vil iterere til enden
variables = {
    'query': '+entityType:/Duck',
    'pageSize': 2
}

generator = cluedin.gql.entries(ctx, query=query, variables=variables)
print(next(generator))
print(next(generator))

Resultat:

{'id': '145afb55-4e78-5dad-b208-633b5b6d19cf', 'name': 'Donald Duck', 'entityType': '/Duck'}
{'id': '17bad60e-6782-5ae5-84bf-7efe05e78e58', 'name': 'Jake McDuck', 'entityType': '/Duck'}

Du kan også indlæse alle entities i en DataFrame. Brug i så fald den maksimale sidestørrelse (10000) for at reducere antallet af kald til serveren:

query = """
query searchEntities($cursor: PagingCursor, $query: String, $pageSize: Int) {
  search(
    query: $query
    cursor: $cursor
    pageSize: $pageSize
    sort: FIELDS,
    sortFields: {field: "id", direction: ASCENDING}
  ) {
    cursor
    entries {
      id
      name
      entityType
    }
  }
}
"""

variables = {
    'query': '+entityType:/Duck',
    'pageSize': 10_000
}

print(pd.DataFrame(cluedin.gql.entries(ctx, query=query, variables=variables)))

Resultat:

                                      id             name entityType
0   145afb55-4e78-5dad-b208-633b5b6d19cf      Donald Duck      /Duck
1   17bad60e-6782-5ae5-84bf-7efe05e78e58      Jake McDuck      /Duck
2   635383a9-9c75-5d61-8f2b-fe496fd82be7       Dewey Duck      /Duck
3   6ae43a44-81b4-5fd7-9c7b-47cb24d407ea     Angus McDuck      /Duck
4   9353b703-13d8-59a1-886c-f40b95283c06  Hortense McDuck      /Duck
5   93b92835-96f2-56a9-98c0-c848236521a9   Matilda McDuck      /Duck
6   a388a77d-7d43-51d1-87b2-efb4f854b5ad    Fergus McDuck      /Duck
7   b2fb05cb-e806-5088-955b-2ff3f9261236   Scrooge McDuck      /Duck
8   b8fc5baf-b679-5e26-abb5-50ca77467992        Huey Duck      /Duck
9   cd8fe1dd-5637-5037-931e-f8bf1a15c0b4       Della Duck      /Duck
10  f5bf5d66-5698-515a-800e-9d778d916dcd       Louie Duck      /Duck

Fra version 2.5.0 af CluedIn Python SDK kan koden ovenfor reduceres til én linje med næsten samme resultat. Metoden returnerer også alle codes og properties for hver entity, hvilket ofte er det, du skal bruge, uden at du behøver kopiere den samme GraphQL-query hver gang:

# dette returnerer alle de forespurgte entiteter med alle properties og codes
print(pd.DataFrame(cluedin.gql.search(ctx, '+entityType:/Duck')))

Hvis du kun skal bruge et udsnit, kan du bruge itertools.islice og sætte en mindre page_size, så SDK'et ikke henter flere data end nødvendigt:

from itertools import islice

# henter en generator, der forespørger entiteter fra serveren tre ad gangen
gen = cluedin.gql.search(ctx, '+entityType:/Duck', page_size=3)

# wrap i en iterator, der stopper efter tre iterationer
iter = islice(gen, 3)

# konverter til DataFrame
df = pd.DataFrame(iter)

print(df)

Den samme kode kan skrives som ét udtryk:

pd.DataFrame(islice(cluedin.gql.search(ctx, '+entityType:/Duck', 3), 3))