API-referanse for Graph Builder (forhåndsversjon)

Med sentinel_graph-klassen kan du samhandle med Microsoft Sentinel grafen, slik at du kan definere grafskjemaet, transformere data fra Microsoft Sentinel datasjøen til noder og kanter, publisere en graf, spørregraf og kjøre avanserte grafalgoritmer. Denne klassen er utformet for å fungere med Spark-økter i Jupyter-notatblokker som kjører på Microsoft Sentinel spark compute.

GraphSpecBuilder

GraphSpecBuilder-klassen gir et flytende verktøy for å opprette grafspesifikasjoner med datasamlebånd og skjemaintegrasjon.

# Deprecated — emits DeprecationWarning
from sentinel_graph.builders.graph_builder import GraphBuilder

# Recommended
from sentinel_graph import GraphSpecBuilder

Konstruktør

GraphSpecBuilder(context: ExecutionContext)

Parametere:

• context (ExecutionContext): Utførelseskontekst som inneholder Spark-økt og konfigurasjon

Reiser:

• ValueError: Hvis konteksten er Ingen eller grafnavn ikke kan fastslås

Statiske metoder

start

GraphSpecBuilder.start(context: Optional[ExecutionContext] = None) -> GraphSpecBuilder

Definer en ny fluent graph builder.

Parametere:

• context (ExecutionContext, valgfritt): ExecutionContext-forekomst. Hvis Ingen, bruker standardkontekst.

Returnerer:

• GraphSpecBuilder: Forekomst av ny byggmester

Eksempel:

builder = GraphSpecBuilder.start(context=context)

Forekomstmetoder

add_node

def add_node(alias: str) -> NodeBuilderInitial

Begynn å bygge en nodedefinisjon.

Parametere:

• alias (str): Unik identifikator for denne noden i grafen

Returnerer:

• NodeBuilderInitial: Nodeverktøy i opprinnelig tilstand

Eksempel:

builder.add_node("user")

add_edge

def add_edge(alias: str) -> EdgeBuilderInitial

Begynn å bygge en kantdefinisjon.

Parametere:

• alias (str): Identifikator for denne kanten i grafen (kan deles på tvers av flere kanter)

Returnerer:

• EdgeBuilderInitial: Edge builder i innledende tilstand

Eksempel:

builder.add_edge("accessed")

done

def done() -> GraphSpec

Fullfør grafspesifikasjonen og returner GraphSpec-forekomsten.

Returnerer:

• GraphSpec: Fullstendig grafspesifikasjon med datasamlebånd og skjema

Reiser:

• ValueError: Hvis grafen har noder eller kanter, eller hvis valideringen mislykkes

Eksempel:

graph_spec = builder.done()

GraphSpec

Grafspesifikasjon med datasamlebånd, skjema og visningsfunksjoner.

Konstruktør

GraphSpec(
    name: str,
    context: ExecutionContext,
    graph_schema: GraphSchema,
    etl_pipeline: Optional[ETLPipeline] = None
)

Parametere:

• name (str): Grafnavn
• context (ExecutionContext): Utføringskontekst
• graph_schema (GraphSchema): Diagramskjemadefinisjon
• etl_pipeline (ETLPipeline, valgfritt): Datasamlebånd for klargjøring av grafer

Egenskaper

nodes

def nodes() -> DataFrame

Hent noder DataFrame (lat, hurtigbufret). Bestemmer automatisk kilden fra datasamlebåndet eller innsjøtabellen.

Returnerer:

• DataFrame: Spark DataFrame som inneholder alle noder

Reiser:

• ValueError: Hvis kontekst mangler eller DataFrames ikke kan lastes inn

edges

def edges() -> DataFrame

Hent edges DataFrame (lat, bufret). Bestemmer automatisk kilden fra datasamlebåndet eller innsjøtabellen.

Returnerer:

• DataFrame: Spark DataFrame som inneholder alle kanter

Reiser:

• ValueError: Hvis kontekst mangler eller DataFrames ikke kan lastes inn

Metoder

build_graph_with_data

def build_graph_with_data() -> Dict[str, Any]

Utfør datasamlebåndet og publiser grafen. Kaller opp internt Graph.build(self), lagrer den returnerte Graph, og returnerer en bakoverkompatibel ordliste.

Returnerer:

• Dict[str, Any]: Ordliste som inneholder:
  • etl_result: Resultater for dataforberedelse
  • api_result: Publisere resultater (hvis vellykket)
  • api_error: Feilstreng (hvis publisering mislyktes)
  • instance_name: Navn på grafforekomst
  • status: "published" eller "prepared"

Eksempel:

graph = Graph.build(spec)
print(f"Status: {graph.build_status.status}")

get_schema

def get_schema() -> GraphSchema

Hent grafskjemaet.

Returnerer:

• GraphSchema: Diagramskjemadefinisjon

get_pipeline

def get_pipeline() -> Optional[ETLPipeline]

Hent datasamlebåndet (Ingen for eksisterende grafer).

Returnerer:

• ETLPipeline eller None: Datasamlebånd hvis tilgjengelig

to_graphframe

def to_graphframe(column_mapping: Optional[Dict[str, str]] = None) -> GraphFrame

Konverter hele grafen til GraphFrame for kjøring av grafalgoritmer. Opererer bare på lokale data (fra datasamlebånd eller innsjøtabell).

Parametere:

• column_mapping (Dikter[str; str], valgfritt): Egendefinert kolonnetilordning med nøkler:
  • "id": Kolonnenavn for ytterpunkt-ID
  • "source_id": Kolonnenavn for Edge-kilde-ID
  • "target_id": Kolonnenavn for mål-ID for Edge

Returnerer:

• GraphFrame: GraphFrame-objekt med alle toppunkt og kanter

Reiser:

• ValueError: Hvis ExecutionContext ikke er tilgjengelig

Eksempel:

gf = graph_spec.to_graphframe()
pagerank = gf.pageRank(resetProbability=0.15, maxIter=10)

show

def show(limit: int = 100, viz_format: str = "visual") -> None

Vis grafdata i ulike formater.

Parametere:

• limit (int, default=100): Maksimalt antall noder/kanter som skal vises
• viz_format (str, default="visual"): Utdataformat
  • "table": Fullstendige DataFrame-tabeller (alle kolonner)
  • "visual": Interaktiv grafvisualisering
  • "all": Vis alle formater

Reiser:

• ValueError: Hvis format ikke er en av verdiene som støttes

Eksempel:

graph_spec.show(limit=50, viz_format="table")

show_schema

def show_schema() -> None

Vis grafskjemaet som en interaktiv grafvisualisering.

Eksempel:

spec.show_schema()

Grafen

Spørringsdiagramforekomst. Opprettet via Graph.get() (eksisterende graf) eller Graph.build() (fra en GraphSpec).

Konstruktør

Graph(
    name: str,
    context: ExecutionContext,
    spec: Optional[GraphSpec] = None,
    build_status: Optional[BuildStatus] = None,
)

Parametere:

• name (str): Grafnavn
• context (ExecutionContext): Utføringskontekst
• spec (GraphSpec, valgfritt): Spesifikasjon for vedlagt graf (angitt av Graph.build())
• build_status (BuildStatus, valgfritt): Bygg resultatmetadata (angitt av Graph.build())

Reiser:

• ValueError: Hvis ExecutionContext er Ingen

Statiske metoder

get

Graph.get(name: str, context: Optional[ExecutionContext] = None) -> Graph

Hent en grafforekomst fra en eksisterende graf. Den returnerte Graph har spec=None og build_status=None.

Parametere:

• name (str): Navn på grafforekomst
• context (ExecutionContext, valgfritt): Kjøringskontekst (som standard er ExecutionContext.default())

Returnerer:

• Graph: Graph-forekomst

Reiser:

• ValueError: Hvis grafnavnet er tomt eller grafforekomsten ikke finnes

Eksempel:

graph = Graph.get("my_graph", context=context)
graph.query("MATCH (n) RETURN n")

prepare

Graph.prepare(spec: GraphSpec) -> Graph

Kjør dataforberedelsesfasen for en GraphSpecuten publisering. Brukes publish() etterpå til å registrere grafen og gjøre den spørringsbar.

Parametere:

• spec (GraphSpec): Grafspesifikasjon som skal klargjøres

Returnerer:

• Graph: Graph-forekomst med spec vedlagt og build_status.status == "prepared"

Reiser:

• ValueError: Hvis spesifikasjonen ikke har noen datasamlebånd eller ingen kjøringskontekst
• RuntimeError: Hvis kjøring av datasamlebånd mislykkes

Eksempel:

spec = GraphSpecBuilder.start(context=ctx).add_node(...).done()
graph = Graph.prepare(spec)
# Inspect results before publishing
graph.nodes.show()
graph.publish()
graph.query("MATCH (n) RETURN n")

build

Graph.build(spec: GraphSpec) -> Graph

Bygg en graf fra en GraphSpec ved å klargjøre data og publisere. Ringer internt Graph.prepare(spec) og prøver graph.publish()deretter . I motsetning til å kalle disse to metodene separat, fanges publiseringsfeil opp – den returnerte grafen har build_status.status == "prepared" og build_status.api_error angitt i stedet for å øke.

Parametere:

• spec (GraphSpec): Grafspesifikasjon å bygge fra

Returnerer:

• Graph: Graph-forekomst med spec vedlagt og build_status utfylt

Reiser:

• ValueError: Hvis spesifikasjonen ikke har noen datasamlebånd eller ingen kjøringskontekst
• RuntimeError: Hvis kjøring av datasamlebånd mislykkes

Eksempel:

spec = GraphSpecBuilder.start(context=ctx).add_node(...).done()
graph = Graph.build(spec)
print(graph.build_status.status)  # "published" or "prepared" (None if neither ran)
graph.query("MATCH (n) RETURN n")

Egenskaper

nodes

def nodes() -> Optional[DataFrame]

Hent nodedataramme. Representanter til self.spec.nodes når en spesifikasjon er vedlagt. Returnerer None ellers.

edges

def edges() -> Optional[DataFrame]

Hent edges DataFrame. Representanter til self.spec.edges når en spesifikasjon er vedlagt. Returnerer None ellers.

schema

def schema() -> Optional[GraphSchema]

Hent grafskjema. Representanter til self.spec.get_schema() når en spesifikasjon er vedlagt. Returnerer None ellers.

Metoder

query

def query(query_string: str, query_language: str = "GQL") -> QueryResult

Utfør en spørring mot grafforekomsten ved hjelp av GQL.

Parametere:

• query_string (str): Diagramspørringsstreng (GQL Language)
• query_language (str, default="GQL"): Spørringsspråk

Returnerer:

• QueryResult: Objekt som inneholder noder, kanter og metadata

Reiser:

• ValueError: Hvis ExecutionContext- eller Spark-økten mangler
• RuntimeError: Hvis klient initialisering eller kjøring av spørring mislykkes

Eksempel:

result = graph.query("MATCH (u:user) WHERE u.age > 30 RETURN u")
result.show()

reachability

def reachability(
    *,
    source_property_value: str = None,
    target_property_value: str = None,
    source_property: Optional[str] = None,
    participating_source_node_labels: Optional[List[str]] = None,
    target_property: Optional[str] = None,
    participating_target_node_labels: Optional[List[str]] = None,
    participating_edge_labels: Optional[List[str]] = None,
    is_directional: bool = True,
    min_hop_count: int = 1,
    max_hop_count: int = 4,
    shortest_path: bool = False,
    max_results: int = 500
) -> QueryResult

[! OBS! reachability(query_input=ReachabilityQueryInput(...)) er fortsatt godtatt, men avgir DeprecationWarning og vil bli fjernet i en fremtidig versjon.

Utfør rekkeviddeanalyse mellom kilde- og målnoder.

Parametere:

• source_property_value (str): Verdien som skal samsvare med kildeegenskapen (validert ved kjøretid. Må angis når du ikke bruker query_input)
• target_property_value (str): Verdien som samsvarer med målegenskapen (validert ved kjøretid. Må angis når du ikke bruker query_input)
• source_property (Valgfritt[str]): Egenskapsnavn for å filtrere kildenoder
• participating_source_node_labels (Valgfritt[Liste[str]]): Nodeetiketter som skal vurderes som kilder
• target_property (Valgfritt[str]): Egenskapsnavn for å filtrere målnoder
• participating_target_node_labels (Valgfritt[Liste[str]]): Nodeetiketter som skal vurderes som mål
• participating_edge_labels (Valgfritt[Liste[str]]): Edge-etiketter som skal traverseres
• is_directional (boolsk): Om kantene er retningsvise (standard: True)
• min_hop_count (int): Minimum mellomhopp (standard: 1)
• max_hop_count (int): Maksimalt antall mellomhopp (standard: 4)
• shortest_path (bool): Returner bare korteste baner (standard: False)
• max_results (int): Maksimalt antall resultater (standard: 500)

Reiser:

• ValueError: Hvis source_property_value eller target_property_value mangler, min_hop_count < 1, max_hop_count < min_hop_counteller max_results < 1
• RuntimeError: Hvis klient initialisering eller kjøring av spørring mislykkes

Returnerer:

• QueryResult: Inneholder banene for rekkevidde

Eksempel:

result = graph.reachability(
    source_property_value="user-001",
    target_property_value="device-003")
result.show()

k_hop

def k_hop(
    *,
    source_property: Optional[str] = None,
    source_property_value: Optional[str] = None,
    participating_source_node_labels: Optional[List[str]] = None,
    target_property: Optional[str] = None,
    target_property_value: Optional[str] = None,
    participating_target_node_labels: Optional[List[str]] = None,
    participating_edge_labels: Optional[List[str]] = None,
    is_directional: bool = True,
    min_hop_count: int = 1,
    max_hop_count: int = 4,
    shortest_path: bool = False,
    max_results: int = 500
) -> QueryResult

Utfør k-hop-analyse fra en gitt kildenode.

Parametere:

• Samme som reachability

Validering:

• Minst én av source_property_value eller target_property_value må angis

Reiser:

• ValueError: Hvis verken source_property_value eller target_property_value er angitt, eller hvis numeriske begrensninger brytes (samme som reachability)
• RuntimeError: Hvis klient initialisering eller kjøring av spørring mislykkes

Returnerer:

• QueryResult: Inneholder k-hop-resultatene

Eksempel:

result = graph.k_hop(source_property_value="user-001")
result.show()

blast_radius

def blast_radius(
    *,
    source_property_value: str = None,
    target_property_value: str = None,
    source_property: Optional[str] = None,
    participating_source_node_labels: Optional[List[str]] = None,
    target_property: Optional[str] = None,
    participating_target_node_labels: Optional[List[str]] = None,
    participating_edge_labels: Optional[List[str]] = None,
    is_directional: bool = True,
    min_hop_count: int = 1,
    max_hop_count: int = 4,
    shortest_path: bool = False,
    max_results: int = 500
) -> QueryResult

Utfør blastradiusanalyse fra kildenode til målnode.

Parametere:

• source_property_value (str): Verdi som identifiserer kildenoden (validert under kjøring. Må angis når du ikke bruker query_input)
• target_property_value (str): Verdi som identifiserer målnoden (validert ved kjøretid. Må angis når du ikke bruker query_input)
• Andre parametere: samme som reachability

Reiser:

• ValueError: Hvis source_property_value eller target_property_value mangler, eller hvis numeriske begrensninger brytes (samme som reachability)
• RuntimeError: Hvis klient initialisering eller kjøring av spørring mislykkes

Returnerer:

• QueryResult: Inneholder resultatene av eksplosjonsradiusen

Eksempel:

result = graph.blast_radius(
    source_property_value="user-003",
    target_property_value="device-003",
    min_hop_count=1)
result.show()

centrality

def centrality(
    *,
    participating_source_node_labels: Optional[List[str]] = None,
    participating_target_node_labels: Optional[List[str]] = None,
    participating_edge_labels: Optional[List[str]] = None,
    threshold: int = 3,
    centrality_type: CentralityType = None,
    max_paths: int = 1000000,
    is_directional: bool = True,
    min_hop_count: int = 1,
    max_hop_count: int = 4,
    shortest_path: bool = False,
    max_results: int = 500
) -> QueryResult

Utfør sentralitetsanalyse i grafen.

Parametere:

• participating_source_node_labels (Valgfritt[Liste[str]]): Kildenodeetiketter
• participating_target_node_labels (Valgfritt[Liste[str]]): Målnodeetiketter
• participating_edge_labels (Valgfritt[Liste[str]]): Edge-etiketter som skal traverseres
• threshold (int): Minimumspoengsum for sentralitet (standard: 3); må være ikke-negativ
• centrality_type (CentralityType): CentralityType.Node eller CentralityType.Edge (standard: None, faller tilbake til CentralityType.Node)
• max_paths (int): Maksimalt antall baner å vurdere (standard: 1000000; 0 = alle baner); må være ikke-negative
• is_directional (boolsk): Om kantene er retningsvise (standard: True)
• min_hop_count (int): Minimum hopp (standard: 1); må være ≥ 1
• max_hop_count (int): Maksimalt antall mellomlag (standard: 4); må være ≥ min_hop_count
• shortest_path (bool): Returner bare korteste baner (standard: False)
• max_results (int): Maksimalt antall resultater (standard: 500); må være ≥ 1

Reiser:

• ValueError: Hvis threshold < 0, max_paths < 0, min_hop_count < 1, max_hop_count < min_hop_counteller max_results < 1
• RuntimeError: Hvis klient initialisering eller kjøring av spørring mislykkes

Returnerer:

• QueryResult: Inneholder måledata for sentralitet

Eksempel:

result = graph.centrality(
    participating_source_node_labels=["user", "device"],
    participating_target_node_labels=["device", "user"],
    participating_edge_labels=["sign_in"],
    is_directional=False)
result.show()

ranked

def ranked(
    *,
    rank_property_name: str = None,
    threshold: int = 0,
    max_paths: int = 1000000,
    decay_factor: float = 1,
    is_directional: bool = True,
    min_hop_count: int = 1,
    max_hop_count: int = 4,
    shortest_path: bool = False,
    max_results: int = 500
) -> QueryResult

Utfør rangert analyse på grafen.

Parametere:

• rank_property_name (str): Egenskapsnavn som skal brukes for rangering (validert ved kjøretid. Må angis når du ikke bruker query_input)
• threshold (int): Returnerer bare baner over denne vekten (standard: 0); må være ikke-negative
• max_paths (int): Maksimalt antall baner å vurdere (standard: 1000000; 0 = alle baner); må være ikke-negative
• decay_factor (flyt): Ranger forfall per trinn; 2 betyr halvering (standard: 1); må være ikke-negativ
• is_directional (boolsk): Om kantene er retningsvise (standard: True)
• min_hop_count (int): Minimum hopp (standard: 1); må være ≥ 1
• max_hop_count (int): Maksimalt antall mellomlag (standard: 4); må være ≥ min_hop_count
• shortest_path (bool): Returner bare korteste baner (standard: False)
• max_results (int): Maksimalt antall resultater (standard: 500); må være ≥ 1

Reiser:

• ValueError: Hvis rank_property_name mangler, threshold < 0, max_paths < 0, decay_factor < 0, min_hop_count < 1, max_hop_count < min_hop_counteller max_results < 1
• RuntimeError: Hvis klient initialisering eller kjøring av spørring mislykkes

Returnerer:

• QueryResult: Inneholder de rangerte nodene/kantene

Eksempel:

result = graph.ranked(
    rank_property_name="risk_score",
    threshold=5,
    decay_factor=2)
result.show()

to_graphframe

def to_graphframe(column_mapping: Optional[Dict[str, str]] = None) -> GraphFrame

Konverter hele grafen til GraphFrame. Bruker spesifikasjonsdata når de er tilgjengelige. leser fra lake tabeller ellers.

Parametere:

• column_mapping (Dikter[str; str], valgfritt): Egendefinert kolonnetilordning

Returnerer:

• GraphFrame: GraphFrame-objekt med alle toppunkt og kanter

Eksempel:

gf = graph.to_graphframe()

show

def show() -> None

Vis grafinformasjon. Representanter til spec.show() for rik visning når en spesifikasjon er vedlagt. Skriver ut minimal informasjon ellers.

show_schema

def show_schema() -> None

Vis diagramskjema. Representanter til spec.show_schema() når en spesifikasjon legges ved. Skriver ut en melding som angir at ingen skjema er tilgjengelig ellers.

publish (nytt i v0.3.3)

def publish() -> Graph

Registrer grafen med API-en, slik at den kan spørres. Kall dette etter Graph.prepare() (eller på noen Graph som har en tilkoblet spesifikasjon) for å publisere grafforekomsten.

Returnerer:

• Graph: Selv for metodekjeding

Reiser:

• ValueError: Hvis ingen spesifikasjoner er tilknyttet eller kontekst mangler
• RuntimeError: Hvis publisering mislykkes

Eksempel:

graph = Graph.prepare(spec)
graph.publish()
# Now the graph is queryable
graph.query("MATCH (n) RETURN n")

BuildStatus

Dataklasse som inneholder metadata fra en Graph.build() operasjon.

Felt

Byggebaner

GraphSpecBuilder.start(...).done()  →  GraphSpec             (spec only, no graph yet)
Graph.get(name, context)            →  Graph (spec=None, build_status=None)
Graph.prepare(spec)                 →  Graph (spec=spec, build_status.status="prepared")
graph.publish()                     →  Graph (build_status.status="published")
Graph.build(spec)                   →  Graph (prepare + publish in one step)

Eksempel:

graph = Graph.build(spec)
if graph.build_status.status == "published":
    print("Graph prepared and published successfully")
elif graph.build_status.status == "prepared":
    print(f"Prepare succeeded but publish failed: {graph.build_status.api_error}")
elif graph.build_status.status is None:
    print("Neither prepare nor publish has run")

Nodeverktøy

NodeBuilderInitial

Opprinnelig tilstand for nodeverktøy: bare tilgjengelige datakildemetoder.

Konstruktør

NodeBuilderInitial(alias: str, graph_builder: GraphSpecBuilder)

Merk: Vanligvis opprettet via GraphSpecBuilder.add_node(), ikke direkte startet.

Metoder

from_table

def from_table(table_name: str, database: Optional[str] = None) -> NodeBuilderSourceSet

Angi tabell som datakilde med intelligent databaseoppløsning.

Parametere:

• table_name (str): Navnet på tabellen (obligatorisk)
• database (str, valgfritt): Eksplisitt databasenavn (har prioritet over kontekststandard)

Returnerer:

• NodeBuilderSourceSet: Builder for videre konfigurasjon

Reiser:

• ValueError: Hvis tabellen ikke ble funnet eller flere motstridende tabeller ble funnet

Rekkefølge for databaseoppløsning:

1. Eksplisitt database parameter (høyeste prioritet)
2. ExecutionContext.default_database
3. Søk i alle databaser (med konfliktgjenkjenning)

Eksempel:

builder.add_node("user").from_table("SigninLogs", database="security_db")

from_dataframe

def from_dataframe(dataframe: DataFrame) -> NodeBuilderSourceSet

Angi Spark DataFrame som datakilde.

Parametere:

• dataframe (DataFrame): Spark DataFrame

Returnerer:

• NodeBuilderSourceSet: Builder for videre konfigurasjon

Eksempel:

df = spark.read.table("users")
builder.add_node("user").from_dataframe(df)

NodeBuilderSourceSet

Nodeverktøy etter at datakilden er angitt: tilgjengelige konfigurasjonsmetoder.

Konstruktør

NodeBuilderSourceSet(alias: str, graph_builder: GraphSpecBuilder, source_step: DataInputETLStep)

Merk: Opprettet internt av kildemetoder for NodeBuilderInitial.

Metoder

with_time_range

def with_time_range(
    time_column: str,
    start_time: Optional[Union[str, datetime]] = None,
    end_time: Optional[Union[str, datetime]] = None,
    lookback_hours: Optional[float] = None
) -> NodeBuilderSourceSet

Bruk tidsområdefiltrering på nodens datakilde.

Parametere:

• time_column (str): Kolonnenavn som inneholder tidsstempeldata (obligatorisk)
• start_time (str eller datetime, valgfritt): Startdato ('20.10.20', '2025-10-20', eller datetime-objekt)
• end_time (str eller datetime, valgfritt): Sluttdato (samme formater som start_time)
• lookback_hours (flyt, valgfritt): Timer å se tilbake fra nå

Returnerer:

• NodeBuilderSourceSet: Selv for metodekjeding

Reiser:

• ValueError: Hvis tidskolonnen ikke ble funnet i kildeskjemaet

Tidsområdelogikk:

1. Hvis start_time og end_time angitt: bruk dem direkte
2. Hvis bare lookback_hours angitt: end=now, start=now-lookback_hours
3. Hvis ingenting er angitt: ingen tidsfiltrering
4. Hvis start/slutt OG lookback_hours: start/slutt har forrang

Eksempel:

# Explicit date range
builder.add_node("user").from_table("SigninLogs") \
    .with_time_range(time_column="TimeGenerated", start_time="2025-01-01", end_time="2025-01-31")

# Lookback window
builder.add_node("user").from_table("SigninLogs") \
    .with_time_range(time_column="TimeGenerated", lookback_hours=24)

with_label

def with_label(label: str) -> NodeBuilderSourceSet

Angi nodeetikett (alias som standard hvis det ikke kalles).

Parametere:

• label (str): Nodeetikett

Returnerer:

• NodeBuilderSourceSet: Selv for metodekjeding

Reiser:

• ValueError: Hvis etiketten allerede er angitt

Eksempel:

builder.add_node("u").from_table("Users").with_label("user")

with_columns

def with_columns(
    *columns: str,
    key: str,
    display: str
) -> NodeBuilderSourceSet

Konfigurer kolonner med nødvendig nøkkel og visningsbetegnelse.

Parametere:

• *columns (str): Kolonnenavn som skal inkluderes (minst ett obligatorisk)
• key (str): Kolonnenavn som skal merkes som nøkkel (obligatorisk, må være i kolonner)
• display (str): Kolonnenavn som skal merkes som visningsverdi (obligatorisk, må være i kolonner, kan være det samme som nøkkelen)

Returnerer:

• NodeBuilderSourceSet: Selv for metodekjeding

Reiser:

• ValueError: Hvis validering mislykkes (dupliserte kolonner, manglende nøkkel/visning osv.)

Merknader:

• Egenskaper bygges automatisk fra kolonnetyper

• Tidsfilterkolonne legges automatisk til hvis angitt

• Egenskapstyper utledes automatisk fra kildeskjema

• Se begrensninger

Eksempel:

builder.add_node("user").from_table("Users") \
    .with_columns("id", "name", "email", "created_at", key="id", display="name")

add_node

def add_node(alias: str) -> NodeBuilderInitial

Fullfør denne noden, og begynn å bygge en annen node.

Parametere:

• alias (str): Alias for den nye noden

Returnerer:

• NodeBuilderInitial: Nytt nodeverktøy

Eksempel:

builder.add_node("user").from_table("Users") \
    .with_columns("id", "name", key="id", display="name") \
    .add_node("device")

add_edge

def add_edge(alias: str) -> EdgeBuilderInitial

Fullfør denne noden, og begynn å bygge en kant.

Parametere:

• alias (str): Alias for kanten

Returnerer:

• EdgeBuilderInitial: Ny kantbygger

Eksempel:

builder.add_node("user").from_table("Users") \
    .with_columns("id", "name", key="id", display="name") \
    .add_edge("accessed")

done

def done() -> GraphSpec

Fullfør denne noden, og fullfør grafspesifikasjonen.

Returnerer:

• GraphSpec: Fullstendig grafspesifikasjon

Eksempel:

graph_spec = builder.add_node("user").from_table("Users") \
    .with_columns("id", "name", key="id", display="name") \
    .done()

Edge Builders

EdgeBuilderInitial

Opprinnelig tilstand for edge builder: bare tilgjengelige datakildemetoder.

Konstruktør

EdgeBuilderInitial(alias: str, graph_builder: GraphSpecBuilder)

Merk: Vanligvis opprettet via GraphSpecBuilder.add_edge(), ikke direkte startet.

Metoder

from_table

def from_table(table_name: str, database: Optional[str] = None) -> EdgeBuilderSourceSet

Angi tabell som datakilde med intelligent databaseoppløsning.

Parametere:

• table_name (str): Navnet på tabellen (obligatorisk)
• database (str, valgfritt): Eksplisitt databasenavn

Returnerer:

• EdgeBuilderSourceSet: Builder for videre konfigurasjon

Reiser:

• ValueError: Hvis tabellen ikke ble funnet eller flere motstridende tabeller ble funnet

Eksempel:

builder.add_edge("accessed").from_table("AccessLogs")

from_dataframe

def from_dataframe(dataframe: DataFrame) -> EdgeBuilderSourceSet

Angi Spark DataFrame som datakilde.

Parametere:

• dataframe (DataFrame): Spark DataFrame

Returnerer:

• EdgeBuilderSourceSet: Builder for videre konfigurasjon

Eksempel:

df = spark.read.table("access_logs")
builder.add_edge("accessed").from_dataframe(df)

EdgeBuilderSourceSet

Edge Builder etter at datakilden er angitt: tilgjengelige konfigurasjonsmetoder.

Konstruktør

EdgeBuilderSourceSet(alias: str, graph_builder: GraphSpecBuilder, source_step: DataInputETLStep)

Merk: Opprettet internt av EdgeBuilderInitial-kildemetoder.

Metoder

with_label

def with_label(label: str) -> EdgeBuilderSourceSet

Angi kantrelasjonstype/-etikett (alias er alias som standard hvis det ikke kalles).

Parametere:

• label (str): Edge-etikett

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekjeding

Reiser:

• ValueError: Hvis etiketten allerede er angitt

Eksempel:

builder.add_edge("rel").from_table("AccessLogs").with_label("ACCESSED")

edge_label

def edge_label(label: str) -> EdgeBuilderSourceSet

Angi kantrelasjonstype/-etikett (alias er alias som standard hvis det ikke kalles).

Parametere:

• label (str): Edge-etikett

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekjeding

Reiser:

• ValueError: Hvis etiketten allerede er angitt

Eksempel:

builder.add_edge("acc").from_table("AccessLogs").edge_label("accessed")

source

def source(id_column: str, node_type: str) -> EdgeBuilderSourceSet

Angi kildenode med ID-kolonne og -etikett.

Parametere:

• id_column (str): Kolonnenavn som inneholder kildenode-ID
• node_type (str): Kildenodeetikett

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekjeding

Reiser:

• ValueError: Hvis kilden allerede er angitt

Eksempel:

builder.add_edge("accessed").from_table("AccessLogs") \
    .source(id_column="user_id", node_type="user")

target

def target(id_column: str, node_type: str) -> EdgeBuilderSourceSet

Angi målnode med ID-kolonne og -etikett.

Parametere:

• id_column (str): Kolonnenavn som inneholder målnode-ID
• node_type (str): Målnodeetikett

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekjeding

Reiser:

• ValueError: Hvis målet allerede er angitt

Eksempel:

builder.add_edge("accessed").from_table("AccessLogs") \
    .source(id_column="user_id", node_type="user") \
    .target(id_column="device_id", node_type="device")

with_time_range

def with_time_range(
    time_column: str,
    start_time: Optional[Union[str, datetime]] = None,
    end_time: Optional[Union[str, datetime]] = None,
    lookback_hours: Optional[float] = None
) -> EdgeBuilderSourceSet

Bruk tidsområdefiltrering på kantens datakilde.

Parametere:

• time_column (str): Kolonnenavn som inneholder tidsstempeldata (obligatorisk)
• start_time (str eller datetime, valgfritt): Startdato
• end_time (str eller datetime, valgfritt): Sluttdato
• lookback_hours (flyt, valgfritt): Timer å se tilbake fra nå

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekjeding

Reiser:

• ValueError: Hvis tidskolonnen ikke ble funnet i kildeskjemaet

Eksempel:

builder.add_edge("accessed").from_table("AccessLogs") \
    .with_time_range(time_column="TimeGenerated", lookback_hours=48)

with_columns

def with_columns(
    *columns: str,
    key: str,
    display: str
) -> EdgeBuilderSourceSet

Konfigurer kolonner med nødvendig nøkkel og visningsbetegnelse.

Parametere:

• *columns (str): Kolonnenavn som skal inkluderes (minst ett obligatorisk)
• key (str): Kolonnenavn som skal merkes som nøkkel (obligatorisk, må være i kolonner)
• display (str): Kolonnenavn som skal merkes som visningsverdi (obligatorisk, må være i kolonner)

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekjeding

Reiser:

• ValueError: Hvis validering mislykkes

Eksempel:

builder.add_edge("accessed").from_table("AccessLogs") \
    .source(id_column="user_id", node_type="user") \
    .target(id_column="device_id", node_type="device") \
    .with_columns("id", "location", "status", key="id", display="location")

add_node

def add_node(alias: str) -> NodeBuilderInitial

Fullfør denne kanten, og begynn å bygge en node.

Parametere:

• alias (str): Alias for den nye noden

Returnerer:

• NodeBuilderInitial: Nytt nodeverktøy

add_edge

def add_edge(alias: str) -> EdgeBuilderInitial

Fullfør denne kanten, og begynn å bygge en annen kant.

Parametere:

• alias (str): Alias for den nye kanten

Returnerer:

• EdgeBuilderInitial: Ny kantbygger

Eksempel:

builder.add_edge("accessed").from_table("AccessLogs") \
    .source(id_column="user_id", node_type="user") \
    .target(id_column="device_id", node_type="device") \
    .with_columns("id", "location", key="id", display="location") \
    .add_edge("connected_to")

done

def done() -> GraphSpec

Fullfør denne kanten og fullfør grafspesifikasjonen.

Returnerer:

• GraphSpec: Fullstendig grafspesifikasjon

Skjemaklasser

GraphDefinitionReference

Referanse til en grafdefinisjon med navn og versjon.

Konstruktør

GraphDefinitionReference(
    fully_qualified_name: str,
    version: str
)

Parametere:

• fully_qualified_name (str): Fullstendig kvalifisert navn på grafen det refereres til
• version (str): Versjon av grafen det refereres til

Reiser:

• ValueError: Hvis fully_qualified_name eller versjonen er tom

Metoder

to_dict

def to_dict() -> Dict[str, Any]

Serialiser til ordliste.

Returnerer:

• Dict[str, Any]: Serialisert referanse

Egenskapen

Egenskapsdefinisjon med typesikkert grensesnitt.

Konstruktør

Property(
    name: str,
    property_type: PropertyType,
    is_non_null: bool = False,
    description: str = "",
    is_key: bool = False,
    is_display_value: bool = False,
    is_internal: bool = False
)

Parametere:

• name (str): Egenskapsnavn
• property_type (PropertyType): Egenskapsdatatype
• is_non_null (boolsk, standard=Usann): Om egenskapen er nødvendig
• description (str, default=""): Egenskapsbeskrivelse
• is_key (boolsk, standard=Usann): Om egenskapen er en nøkkel
• is_display_value (boolsk, standard=Usann): Om egenskapen er visningsverdi
• is_internal (boolsk, standard=Usann): Om egenskapen er intern

Reiser:

• ValueError: Hvis navnet er tomt eller valideringen mislykkes

Klassemetoder

key

@classmethod
Property.key(
    name: str,
    property_type: PropertyType,
    description: str = "",
    is_non_null: bool = False
) -> Property

Opprett en nøkkelegenskap med vanlige innstillinger (is_key=Sann, is_display_value=Sann).

display

@classmethod
Property.display(
    name: str,
    property_type: PropertyType,
    description: str = "",
    is_non_null: bool = False
) -> Property

Opprett en visningsverdiegenskap (is_display_value=Sann).

Metoder

describe

def describe(text: str) -> Property

Legg til beskrivelse flytende.

Parametere:

• text (str): Beskrivelsestekst

Returnerer:

• Property: Selv for metodekjeding

to_dict

def to_dict() -> Dict[str, Any]

Serialiser egenskapen til ordlisten med @-prefikserte merknadsnøkler.

Returnerer:

• Dict[str, Any]: Serialisert egenskap

to_gql

def to_gql() -> str

Generer egenskapsdefinisjon for GQL.

Returnerer:

• str: GQL streng representasjon

EdgeNode

Nodereferanse brukt i kantdefinisjoner.

Konstruktør

EdgeNode(
    alias: Optional[str] = None,
    labels: List[str] = []
)

Parametere:

• alias (str, valgfritt): Nodealias (automatisk satt til første etikett hvis ingen eller tom)
• labels (List[str]): Nodeetiketter (minst én obligatorisk)

Reiser:

• ValueError: Hvis etikettlisten er tom
• TypeError: Hvis etiketter ikke er strenger

Automutasjon:

• Hvis aliaset er Ingen eller tomt, settes det til den første etiketten

Metoder

to_dict

def to_dict() -> Dict[str, Any]

Serialiser til ordliste.

Returnerer:

• Dict[str, Any]: Referanse for serialisert kantnode

Node

Nodedefinisjon med typesikkert grensesnitt.

Konstruktør

Node(
    alias: str = "",
    labels: List[str] = [],
    implies_labels: List[str] = [],
    properties: List[Property] = [],
    description: str = "",
    entity_group: str = "",
    dynamic_labels: bool = False,
    abstract_edge_aliases: bool = False
)

Parametere:

• alias (str, default=""): Nodealias (automatisk satt til første etikett hvis tom)
• labels (List[str]): Nodeetiketter (minst én obligatorisk)
• implies_labels (List[str], default=[]): Underforståtte etiketter
• properties (List[Property], default=[]): Nodeegenskaper
• description (str, default=""): Beskrivelse av node
• entity_group (str, default=""): Enhetsgruppenavn
• dynamic_labels (boolsk, standard=Usann): Om noden har dynamiske etiketter
• abstract_edge_aliases (boolsk, standard=Usann): Om noden bruker abstrakte kantaliaser

Reiser:

• ValueError: Hvis validering mislykkes (ingen etiketter, ingen nøkkelegenskap, ingen visningsegenskap osv.)

Automutasjon:

• Hvis aliaset er tomt, settes det til den første etiketten
• Hvis entity_group er tom, settes den til primæretiketten

Metoder

get_primary_label

def get_primary_label() -> Optional[str]

Hent den primære (første) etiketten.

Returnerer:

• str eller None: Primæretikett eller Ingen hvis ingen etiketter

get_entity_group_name

def get_entity_group_name() -> str

Hent enhetsgruppenavn eller tilbakefall til primæretikett.

Returnerer:

• str: Navn på enhetsgruppe

get_primary_key_property_name

def get_primary_key_property_name() -> Optional[str]

Hent navnet på primærnøkkelegenskapen.

Returnerer:

• str eller None: Egenskapsnavn for primærnøkkel

get_properties

def get_properties() -> Dict[str, Property]

Få egenskaper som en ordliste for enkel tilgang.

Returnerer:

• Dict[str, Property]: Egenskaper som er tastet inn etter navn

get_property

def get_property(name: str) -> Optional[Property]

Hent en bestemt egenskap etter navn.

Parametere:

• name (str): Egenskapsnavn

Returnerer:

• Property eller None: Egenskap hvis funnet

add_property

def add_property(prop: Property) -> None

Legg til en egenskap i denne noden.

Parametere:

• prop (Egenskap): Egenskap som skal legges til

Reiser:

• ValueError: Hvis egenskapsnavnet er duplisert

is_dynamically_labeled

def is_dynamically_labeled() -> bool

Kontroller om noden har dynamiske etiketter.

Returnerer:

• bool: Sann hvis dynamiske etiketter er aktivert

is_abstract_edge_node_aliases

def is_abstract_edge_node_aliases() -> bool

Kontroller om noden bruker aliaser for abstrakt kantnode.

Returnerer:

• bool: Sann hvis abstrakte kantaliaser er aktivert

describe

def describe(text: str) -> Node

Legg til beskrivelse flytende.

Parametere:

• text (str): Beskrivelsestekst

Returnerer:

• Node: Selv for metodekjeding

to_dict

def to_dict() -> Dict[str, Any]

Serialiser node til ordliste.

Returnerer:

• Dict[str, Any]: Serialisert node

to_gql

def to_gql() -> str

Generer AVREFL-nodedefinisjon.

Returnerer:

• str: GQL streng representasjon

Reiser:

• ValueError: Hvis noden mangler obligatoriske felt for GQL

Klassemetoder

create

@classmethod
Node.create(
    alias: str,
    labels: List[str],
    properties: List[Property],
    description: str = "",
    entity_group: str = "",
    **kwargs
) -> Node

Opprett en node med alle obligatoriske felt.

Parametere:

• alias (str): Nodealias
• labels (List[str]): Nodeetiketter
• properties (Liste[Egenskap]): Nodeegenskaper
• description (str, default=""): Beskrivelse av node
• entity_group (str, default=""): Enhetsgruppenavn

Returnerer:

• Node: Ny nodeforekomst

Kanten

Edge-definisjon med typesikkert grensesnitt.

Konstruktør

Edge(
    relationship_type: str,
    source_node_label: str,
    target_node_label: str,
    direction: EdgeDirection = EdgeDirection.DIRECTED_RIGHT,
    properties: List[Property] = [],
    description: str = "",
    entity_group: str = "",
    dynamic_type: bool = False
)

Parametere:

• relationship_type (str): Kantrelasjonstype (for eksempel «FØLGER», «EIER»)
• source_node_label (str): Kildenodeetikett
• target_node_label (str): Målnodeetikett
• direction (EdgeDirection, default=DIRECTED_RIGHT): Edge-retning
• properties (List[Property], default=[]): Edge-egenskaper
• description (str, default=""): Edge-beskrivelse
• entity_group (str, default=""): Enhetsgruppenavn
• dynamic_type (boolsk, standard=Usann): Om kanten har dynamisk type

Reiser:

• ValueError: Hvis validering mislykkes

Automutasjon:

• labels listen fylles ut automatisk med [relationship_type]
• Hvis entity_group er tom, er den satt til relationship_type

Egenskaper

edge_type

def edge_type() -> str

Bakoverkompatibilitetsalias for relationship_type.

Returnerer:

• str: Relasjonstype

Metoder

get_entity_group_name

def get_entity_group_name() -> str

Hent enhetsgruppenavn eller tilbakefall til relasjonstype.

Returnerer:

• str: Navn på enhetsgruppe

is_dynamic_type

def is_dynamic_type() -> bool

Kontroller om kanten har dynamisk type.

Returnerer:

• bool: Sann hvis dynamisk type

add_property

def add_property(edge_property: Property) -> None

Legg til en egenskap i denne kanten.

Parametere:

• edge_property (Egenskap): Egenskap som skal legges til

describe

def describe(text: str) -> Edge

Legg til beskrivelse flytende.

Parametere:

• text (str): Beskrivelsestekst

Returnerer:

• Edge: Selv for metodekjeding

to_dict

def to_dict() -> Dict[str, Any]

Serialiser kant til ordliste.

Returnerer:

• Dict[str, Any]: Serialisert kant

to_gql

def to_gql() -> str

Generer AVREFL-kantdefinisjon.

Returnerer:

• str: GQL streng representasjon

Klassemetoder

create

Edge.create(
    relationship_type: str,
    source_node_label: str,
    target_node_label: str,
    properties: List[Property] = None,
    description: str = "",
    entity_group: str = "",
    **kwargs
) -> Edge

Opprett en kant med alle obligatoriske felt.

Parametere:

• relationship_type (str): Kantrelasjonstype
• source_node_label (str): Kildenodeetikett
• target_node_label (str): Målnodeetikett
• properties (Liste[Egenskap], valgfritt): Edge-egenskaper
• description (str, default=""): Edge-beskrivelse
• entity_group (str, default=""): Enhetsgruppenavn

Returnerer:

• Edge: Ny edge-forekomst

GraphSchema

Diagramskjemadefinisjon med typesikkert grensesnitt.

Konstruktør

GraphSchema(
    name: str,
    nodes: List[Node] = [],
    edges: List[Edge] = [],
    base_graphs: List[GraphSchema] = [],
    description: str = "",
    version: str = "1.0",
    fully_qualified_name: str = "",
    namespace: str = ""
)

Parametere:

• name (str): Diagramskjemanavn
• nodes (List[Node], default=[]): Nodedefinisjoner
• edges (List[Edge], default=[]): Edge-definisjoner
• base_graphs (List[GraphSchema], default=[]): Base graph schemas
• description (str, default=""): Skjemabeskrivelse
• version (str, default="1.0"): Skjemaversjon
• fully_qualified_name (str, default=""): Fullstendig kvalifisert navn
• namespace (str, default=""): Navneområde

Reiser:

• ValueError: Hvis validering mislykkes (dupliserte aliaser, kantreferanse ikke-eksisterende noder osv.)

Metoder

get_fully_qualified_name

def get_fully_qualified_name() -> str

Få fullstendig kvalifisert navn.

Returnerer:

• str: Fullstendig kvalifisert navn

get_namespace

def get_namespace() -> str

Hent navneområde fra fullstendig navn eller returstandard.

Returnerer:

• str:Navneområdet

get_version

def get_version() -> str

Hent versjon.

Returnerer:

• str: Versjonsstreng

get_node

def get_node(label_or_alias: str) -> Optional[Node]

Hent node etter etikett eller alias.

Parametere:

• label_or_alias (str): Nodeetikett eller alias

Returnerer:

• Node eller None: Node hvis funnet

get_edge

def get_edge(name: str) -> Optional[Edge]

Få edge etter navn/type.

Parametere:

• name (str): Kantrelasjonstype

Returnerer:

• Edge eller None: Edge hvis funnet

add_node

def add_node(node: Node) -> None

Legg til en node i dette diagrammet.

Parametere:

• node (Node): Node som skal legges til

Reiser:

• ValueError: Hvis nodealias er duplisert

add_edge

def add_edge(edge: Edge) -> None

Legg til en kant i denne grafen.

Parametere:

• edge (Edge): Kant som skal legges til

Reiser:

• ValueError: Hvis kanttype er duplisert

include_graph

def include_graph(fully_qualified_name: str, version: str) -> GraphSchema

Legg til en grafinkludering (fluent API).

Parametere:

• fully_qualified_name (str): Fullt kvalifisert navn på grafen som skal inkluderes
• version (str): Versjon av grafen som skal inkluderes

Returnerer:

• GraphSchema: Selv for metodekjeding

get_included_graph_references

def get_included_graph_references() -> List[GraphDefinitionReference]

Få en liste over inkluderte grafreferanser.

Returnerer:

• List[GraphDefinitionReference]: Liste over grafdefinisjonsreferanser

describe

def describe(text: str) -> GraphSchema

Legg til beskrivelse flytende.

Parametere:

• text (str): Beskrivelsestekst

Returnerer:

• GraphSchema: Selv for metodekjeding

to_dict

def to_dict() -> Dict[str, Any]

Serialiser skjema til ordliste.

Returnerer:

• Dict[str, Any]: Serialisert skjema

to_json

def to_json(indent: int = 2) -> str

Generer JSON-representasjon.

Parametere:

• indent (int, default=2): JSON-innrykksnivå

Returnerer:

• str: JSON-streng

to_gql

def to_gql() -> str

Generer GQL-skjemadefinisjon.

Returnerer:

• str: GQL streng representasjon

Klassemetoder

create

@classmethod
GraphSchema.create(
    name: str,
    nodes: List[Node] = None,
    edges: List[Edge] = None,
    description: str = "",
    version: str = "1.0",
    **kwargs
) -> GraphSchema

Opprett et grafskjema med alle obligatoriske felt.

Parametere:

• name (str): Diagramskjemanavn
• nodes (List[Node], valgfritt): Nodedefinisjoner
• edges (Liste[Edge], valgfritt): Edge-definisjoner
• description (str, default=""): Skjemabeskrivelse
• version (str, default="1.0"): Skjemaversjon

Returnerer:

• GraphSchema: Ny diagramskjemaforekomst

Spørringsinndataklasser

Dataklasser som representerer inndataparametere for forhåndsdefinerte grafspørringer.

QueryInputBase

Basisklasse for alle spørringsinndataparametere.

Metoder

to_json_payload

def to_json_payload() -> Dict[str, Any]

Konverter inndataparameterne til en ordliste for API-innsending.

Returnerer:

• Dict[str, Any]: Ordlisterepresentasjon av inndataparameterne

validate

def validate() -> None

Valider inndataparameterne.

Reiser:

• ValueError: Hvis inndataparameterne er ugyldige

ReachabilityQueryInput

Inndataparametere for en reachability-spørring mellom kilde- og målnoder. Arver ReachabilityQueryInputBase som arver fra QueryInputBase.

Felt

Validering:

• source_property_value er obligatorisk
• target_property_value er obligatorisk

Eksempel:

# Preferred: keyword arguments (no import needed)
result = graph.reachability(
    source_property="UserId",
    source_property_value="user123",
    target_property="DeviceId",
    target_property_value="device456",
    participating_edge_labels=["accessed", "connected_to"],
    shortest_path=True
)

# DEPRECATED — will be removed in a future version. Use keyword arguments above.
from sentinel_graph.builders.query_input import ReachabilityQueryInput
result = graph.reachability(query_input=ReachabilityQueryInput(
    source_property_value="user123",
    target_property_value="device456"
))

K_HopQueryInput

Inndataparametere for en k-hop-spørring fra en gitt kildenode. Arver fra ReachabilityQueryInputBase.

Arver alle felt fra ReachabilityQueryInput.

Validering:

• Minst én av source_property_value eller target_property_value må angis

Eksempel:

# Preferred: keyword arguments
result = graph.k_hop(
    source_property_value="user123",
    max_hop_count=3,
    participating_edge_labels=["accessed"]
)

# DEPRECATED — will be removed in a future version. Use keyword arguments above.
from sentinel_graph.builders.query_input import K_HopQueryInput
result = graph.k_hop(query_input=K_HopQueryInput(source_property_value="user123"))

BlastRadiusQueryInput

Inndataparametere for en blastradiusspørring fra kilde til målnoder. Arver fra ReachabilityQueryInputBase.

Arver alle felt fra ReachabilityQueryInput, med følgende obligatoriske felt:

Validering:

• source_property_value er obligatorisk
• target_property_value er obligatorisk

Eksempel:

# Preferred: keyword arguments
result = graph.blast_radius(
    source_property_value="user123",
    target_property_value="device456",
    participating_edge_labels=["accessed", "connected_to"]
)

# DEPRECATED — will be removed in a future version. Use keyword arguments above.
from sentinel_graph.builders.query_input import BlastRadiusQueryInput
result = graph.blast_radius(query_input=BlastRadiusQueryInput(
    source_property_value="user123",
    target_property_value="device456"
))

CentralityQueryInput

Inndataparametere for en spørring for sentralitetsanalyse. Arver fra QueryInputBase.

Sentralitetstype-opplisting

Felt

Eksempel:

# Preferred: keyword arguments (works for all centrality types)
result = graph.centrality(
    centrality_type=CentralityType.Edge,  # or CentralityType.Node (default)
    participating_edge_labels=["accessed", "connected_to"],
    threshold=5,
    max_results=100
)

# DEPRECATED — will be removed in a future version. Use keyword arguments above.
from sentinel_graph.builders.query_input import CentralityQueryInput, CentralityType
result = graph.centrality(query_input=CentralityQueryInput(
    centrality_type=CentralityType.Edge,
    participating_edge_labels=["accessed"]
))

RankedQueryInput

Inndataparametere for en rangert analysespørring. Arver fra QueryInputBase.

Felt

Eksempel:

# Preferred: keyword arguments
result = graph.ranked(
    rank_property_name="risk_score",
    threshold=5,
    decay_factor=2,
    max_results=50
)

# DEPRECATED — will be removed in a future version. Use keyword arguments above.
from sentinel_graph.builders.query_input import RankedQueryInput
result = graph.ranked(query_input=RankedQueryInput(
    rank_property_name="risk_score",
    threshold=5
))

Spørringsresultater

QueryResult

Resultat fra en grafspørring med forsinket DataFrame-tilgang.

Konstruktør

QueryResult(raw_response: Dict[str, Any], graph: Graph)

Parametere:

• raw_response (Dict[str, Any]): Rå API-svarordliste
• graph (Graf): Referanse til overordnet graf

Merk: Vanligvis opprettet av Graph.query(), ikke direkte startet.

Metoder

to_dataframe

def to_dataframe() -> DataFrame

Konverterer spørringsresultatet til en Spark DataFrame.

Returnerer:

• DataFrame: Spørringsresultat som Spark DataFrame

Reiser:

• ValueError: Hvis konverteringen mislykkes

Eksempel:

result = graph.query("MATCH (u:user) RETURN u")
df = result.to_dataframe()
df.show()

get_raw_data

def get_raw_data() -> Dict[str, Any]

Få RawData-inndelingen fra svar.

Returnerer:

• Dict[str, Any]: Ordliste med rå metadata eller tom diktering hvis den ikke finnes

Eksempel:

result = graph.query("MATCH (u:user) RETURN u")
metadata = result.get_raw_data()

show

def show(format: str = "visual") -> None

Vis spørringsresultat i ulike formater.

Parametere:

• format (str, default="visual"): Utdataformat
  • "table": Fullstendige DataFrame-tabeller (alle kolonner)
  • "visual": Interaktiv grafvisualisering med VSC-plugin-modul
  • "all": Vis alle formater

Reiser:

• ValueError: Hvis format ikke er en av verdiene som støttes

Eksempel:

result = graph.query("MATCH (u:user)-[r:accessed]->(d:device) RETURN u, r, d")
result.show()  # Visual by default
result.show(format="table")  # Table format

Fullstendig eksempel (anbefales – v0.3+)

# 0. Imports
from sentinel_graph import GraphSpecBuilder, Graph

# 1. Define graph specification
spec = (
    GraphSpecBuilder.start()
    
    .add_node("User")
        .from_dataframe(user_nodes)  # native Spark DF from groupBy → no .df
            .with_columns(
                "UserId", "UserDisplayName", "UserPrincipalName",
                "DistinctLocationCount", "DistinctIPCount", "DistinctAppCount",
                "TotalSignIns", "RiskySignInCount", "ImpossibleTravelFlag",
                key="UserId", display="UserDisplayName"
            )
    
    .add_node("IPAddress")
        .from_dataframe(ip_nodes)  # native Spark DF from groupBy → no .df
            .with_columns(
                "IPAddress", "UniqueUsers", "UniqueLocations",
                "SignInCount", "RiskySignInCount", "SharedIPFlag",
                key="IPAddress", display="IPAddress"
            )
    
    .add_edge("UsedIP")
        .from_dataframe(edge_used_ip)  # native Spark DF → no .df
            .source(id_column="UserId", node_type="User")
            .target(id_column="IPAddress", node_type="IPAddress")
            .with_columns(
                "SignInCount", "FirstSeen", "LastSeen", "EdgeKey",
                key="EdgeKey", display="EdgeKey"
            )
   
    .done()
)

# 2. Inspect schema before building (GraphSpec owns this)
spec.show_schema()

# 3. Build: prepares data + publishes graph → returns Graph
graph = Graph.build(spec)
print(f"Build status: {graph.build_status.status}")

# 4. Query the graph (query lives on Graph)
result = graph.query("MATCH (u:user)-[used:UsedIP]->(ip:IPAddress) RETURN * LIMIT 100")
result.show()

# 5. Access data via delegation
df = result.to_dataframe()
df.printSchema()

# 6. Graph algorithms
gf = graph.to_graphframe()
pagerank_result = gf.pageRank(resetProbability=0.15, maxIter=10)
pagerank_result.vertices.select("id", "pagerank").show()

# 7. Fetch an existing graph (no spec needed)
graph = Graph.get("my_existing_graph", context=context)
graph.query("MATCH (n) RETURN n LIMIT 10").show()

Notater om utformingsmønstre

Fluent API

Alle byggere støtter metodekjedering for lesbare, deklarative grafdefinisjoner:

builder.add_node("user") \
    .from_table("Users") \
    .with_columns("id", "name", key="id", display="name") \
    .add_edge("follows")

Unionsskjemaer

Flere kanter med samme alias blir automatisk unionert med sammenslåtte egenskaper:

# Both edges use alias "sign_in" - they will be merged into one schema edge
builder.add_edge("sign_in") \
    .from_table("AzureSignins") \
    .source(id_column="UserId", node_type="AZuser") \
    .target(id_column="DeviceId", node_type="device")

builder.add_edge("sign_in") \
    .from_table("EntraSignins") \
    .source(id_column="UserId", node_type="EntraUser") \
    .target(id_column="DeviceId", node_type="device")

Autokonfigurering

Mange felt har fornuftige standarder:

• Node-/kantetiketter er som standard aliaser
• Egenskaper utledes automatisk fra kildeskjemaer
• Enhetsgrupper bruker primæretiketter/relasjonstyper som standard

Forsinket evaluering

DataFrames og ressurser lastes inn lazily og bufret:

• graph_spec.nodes og graph_spec.edges lastes inn ved første tilgang
• Spørringsresultater oppretter datarammer bare når de blir bedt om det

Beslektet innhold

• Oversikt over egendefinerte grafer
• Opprette egendefinerte grafer