Api-reference til Graph Builder (prøveversion)

Den sentinel_graph klasse gør det muligt at interagere med grafen Microsoft Sentinel, så du kan definere dit grafskema, transformere data fra den Microsoft Sentinel datasø til noder og kanter, publicere en graf, en forespørgselsgraf og køre avancerede grafalgoritmer. Denne klasse er udviklet til at fungere sammen med Spark-sessioner i Jupyter-notesbøger, der kører på Microsoft Sentinel spark-beregning.

GraphSpecBuilder

Klassen GraphSpecBuilder giver en flydende generator til oprettelse af grafspecifikationer med datapipelines og skemaintegration.

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

# Recommended
from sentinel_graph import GraphSpecBuilder

Konstruktør

GraphSpecBuilder(context: ExecutionContext)

Parametre:

• context (ExecutionContext): Udførelseskontekst, der indeholder Spark-session og -konfiguration

Rejser:

• ValueError: Hvis konteksten er None eller graph name kan ikke bestemmes

Statiske metoder

start

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

Definer en ny flydende grafgenerator.

Parametre:

• context (ExecutionContext, valgfrit): ExecutionContext-forekomst. Hvis Ingen, bruges standardkontekst.

Returnerer:

• GraphSpecBuilder, ny forekomst af generator

Eksempel:

builder = GraphSpecBuilder.start(context=context)

Metoder til forekomst

add_node

def add_node(alias: str) -> NodeBuilderInitial

Begynd at oprette en nodedefinition.

Parametre:

• alias (str): Entydigt id for denne node i grafen

Returnerer:

• NodeBuilderInitial: Nodegenerator i starttilstand

Eksempel:

builder.add_node("user")

add_edge

def add_edge(alias: str) -> EdgeBuilderInitial

Begynd at oprette en edge-definition.

Parametre:

• alias (str): Identifikator for denne kant i grafen (kan deles på tværs af flere kanter)

Returnerer:

• EdgeBuilderInitial: Edge Builder i starttilstand

Eksempel:

builder.add_edge("accessed")

done

def done() -> GraphSpec

Afslut grafspecifikationen, og returner forekomsten GraphSpec.

Returnerer:

• GraphSpec: Komplet grafspecifikation med datapipeline og skema

Rejser:

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

Eksempel:

graph_spec = builder.done()

GraphSpec

Grafspecifikation med datapipeline, skema og visningsfunktioner.

Konstruktør

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

Parametre:

• name (str): Grafnavn
• context (ExecutionContext): Udførelseskontekst
• graph_schema (GraphSchema): Grafskemadefinition
• etl_pipeline (ETLPipeline, valgfrit): Datapipeline til grafforberedelse

Egenskaber

nodes

def nodes() -> DataFrame

Hent noderne DataFrame (doven, cachelagret). Bestemmer automatisk kilde fra datapipeline eller søtabel.

Returnerer:

• DataFrame: Spark DataFrame, der indeholder alle noder

Rejser:

• ValueError: Hvis konteksten mangler, eller DataFrames ikke kan indlæses

edges

def edges() -> DataFrame

Hent kanter DataFrame (doven, cachelagret). Bestemmer automatisk kilde fra datapipeline eller søtabel.

Returnerer:

• DataFrame, Spark DataFrame, der indeholder alle kanter

Rejser:

• ValueError: Hvis konteksten mangler, eller DataFrames ikke kan indlæses

Metoder

build_graph_with_data

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

Udfør datapipelinen, og publicer grafen. Internt kalder Graph.build(self), gemmer den returnerede Graphog returnerer en bagudkompatibel ordbog.

Returnerer:

• Dict[str, Any]: Ordbog, der indeholder:
  • etl_result: Resultater af dataforberedelse
  • api_result, publicere resultater (hvis det lykkes)
  • api_error: Fejlstreng (hvis publicering mislykkedes)
  • instance_name: Navn på diagramforekomst
  • status: "published" eller "prepared"

Eksempel:

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

get_schema

def get_schema() -> GraphSchema

Hent grafskemaet.

Returnerer:

• GraphSchema: Grafskemadefinition

get_pipeline

def get_pipeline() -> Optional[ETLPipeline]

Hent datapipelinen (ingen for eksisterende grafer).

Returnerer:

• ETLPipeline eller None: Datapipeline, hvis den er tilgængelig

to_graphframe

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

Konvertér hele grafen til GraphFrame for at køre grafalgoritmer. Fungerer kun på lokale data (fra datapipeline eller søtabel).

Parametre:

• column_mapping (Dict[str, str], valgfrit): Brugerdefineret kolonnetilknytning med nøgler:
  • "id", kolonnenavn for knude-id
  • "source_id": Kolonnenavn for Edge-kilde-id
  • "target_id": Kolonnenavn for Edge-destinations-id

Returnerer:

• GraphFrame: GraphFrame-objekt med alle knudepunkter og kanter

Rejser:

• ValueError: Hvis ExecutionContext ikke er tilgængelig

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 forskellige formater.

Parametre:

• limit (int, default=100): Maksimalt antal noder/kanter, der skal vises
• viz_format (str, default="visual"): Outputformat
  • "table", komplette DataFrame-tabeller (alle kolonner)
  • "visual", interaktiv grafvisualisering
  • "all": Vis alle formater

Rejser:

• ValueError: Hvis format ikke er en af de understøttede værdier

Eksempel:

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

show_schema

def show_schema() -> None

Vis grafskemaet som en interaktiv grafvisualisering.

Eksempel:

spec.show_schema()

Graf

Grafforekomst, der kan forespørges på. Oprettet 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,
)

Parametre:

• name (str): Grafnavn
• context (ExecutionContext): Udførelseskontekst
• spec (GraphSpec, valgfrit): Vedhæftet grafspecifikation (angivet af Graph.build())
• build_status (BuildStatus, valgfrit): Byg resultatmetadata (angivet af Graph.build())

Rejser:

• ValueError: Hvis ExecutionContext ikke er nogen

Statiske metoder

get

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

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

Parametre:

• name (str): Navn på grafforekomst
• context (ExecutionContext, valgfrit): Udførelseskontekst (standard til ExecutionContext.default())

Returnerer:

• Graph: Grafforekomst

Rejser:

• ValueError: Hvis grafnavnet er tomt, eller grafforekomsten ikke findes

Eksempel:

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

prepare

Graph.prepare(spec: GraphSpec) -> Graph

Kør fasen til dataforberedelse for en GraphSpecuden at publicere. Brug publish() derefter til at registrere grafen og gøre det muligt at forespørge på den.

Parametre:

• spec (GraphSpec): Grafspecifikation, der skal forberedes

Returnerer:

• Graph: Grafforekomst med spec vedhæftet og build_status.status == "prepared"

Rejser:

• ValueError: Hvis specifikationen ikke har nogen datapipeline eller ingen udførelseskontekst
• RuntimeError: Hvis udførelsen af datapipeline 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

Opret en graf ud fra en GraphSpec ved at forberede data og publicere. Internt kald Graph.prepare(spec) og forsøger graph.publish()derefter . I modsætning til at kalde disse to metoder separat, registreres publiceringsfejl – den returnerede graf har build_status.status == "prepared" og build_status.api_error er angivet i stedet for at hæve.

Parametre:

• spec (GraphSpec): Grafspecifikation, der skal bygges ud fra

Returnerer:

• Graph: Diagramforekomst med spec vedhæftet og build_status udfyldt

Rejser:

• ValueError: Hvis specifikationen ikke har nogen datapipeline eller ingen udførelseskontekst
• RuntimeError: Hvis udførelsen af datapipeline 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")

Egenskaber

nodes

def nodes() -> Optional[DataFrame]

Hent noderne DataFrame. Uddelegerer til self.spec.nodes , når en specifikation er vedhæftet. Returnerer ellers None .

edges

def edges() -> Optional[DataFrame]

Hent kanter DataFrame. Uddelegerer til self.spec.edges , når en specifikation er vedhæftet. Returnerer ellers None .

schema

def schema() -> Optional[GraphSchema]

Hent grafskema. Uddelegerer til self.spec.get_schema() , når en specifikation er vedhæftet. Returnerer ellers None .

Metoder

query

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

Udfør en forespørgsel i forhold til grafforekomsten ved hjælp af GQL.

Parametre:

• query_string (str): Grafforespørgselsstreng (GQL-sprog)
• query_language (str, default="GQL"): Forespørgselssprog

Returnerer:

• QueryResult: Objekt, der indeholder noder, kanter og metadata

Rejser:

• ValueError: Hvis ExecutionContext eller Spark-sessionen mangler
• RuntimeError: Hvis klientinitialisering eller udførelse af forespørgsler 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

[! BEMÆRK! reachability(query_input=ReachabilityQueryInput(...)) er stadig accepteret, men udsender DeprecationWarning og fjernes i en fremtidig version.

Udfør analyse af rækkevidden mellem kilde- og destinationsnoder.

Parametre:

• source_property_value (str): Værdi, der svarer til kildeegenskaben (valideret på kørselstidspunktet. Skal angives, når der ikke bruges query_input)
• target_property_value (str): Værdi, der svarer til destinationsegenskaben (valideret på kørselstidspunktet. Skal angives, når der ikke bruges query_input)
• source_property (Valgfrit[str]): Egenskabsnavn til filtrering af kildenoder
• participating_source_node_labels (Valgfri[List[str]]): Nodenavne, der skal overvejes som kilder
• target_property (Valgfrit[str]): Egenskabsnavn til filtrering af destinationsnoder
• participating_target_node_labels (Valgfri[List[str]]): Nodenavne, der skal overvejes som mål
• participating_edge_labels (Valgfri[List[str]]): Edge-mærkater, der skal gennemgås
• is_directional (bool): Om kanterne er retningsbestemt (standard: True)
• min_hop_count (int): Minimumhop (standard: 1)
• max_hop_count (int): Maksimalt antal hop (standard: 4)
• shortest_path (bool): Returner kun korteste stier (standard: False)
• max_results (int): Maksimalt antal resultater (standard: 500)

Rejser:

• 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 klientinitialisering eller udførelse af forespørgsler mislykkes

Returnerer:

• QueryResult: Indeholder rækkeviddestierne

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

Udfør k-hop-analyse fra en given kildenode.

Parametre:

• Samme som reachability

Validering:

• Der skal angives mindst én af source_property_value eller target_property_value

Rejser:

• ValueError: Hvis hverken source_property_value er angivet eller target_property_value angivet, eller hvis numeriske begrænsninger krænkes (samme som reachability)
• RuntimeError: Hvis klientinitialisering eller udførelse af forespørgsler mislykkes

Returnerer:

• QueryResult: Indeholder k-hop-resultaterne

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

Udfør analyse af eksplosionsradius fra kildenode til destinationsnode.

Parametre:

• source_property_value (str): Værdi, der identificerer kildenoden (valideret på kørselstidspunktet. Skal angives, når der ikke bruges query_input)
• target_property_value (str): Værdi, der identificerer destinationsnoden (valideret på kørselstidspunktet. Skal angives, når der ikke bruges query_input)
• Andre parametre: samme som reachability

Rejser:

• ValueError: Hvis source_property_value eller target_property_value mangler, eller hvis numeriske begrænsninger krænkes (samme som reachability)
• RuntimeError: Hvis klientinitialisering eller udførelse af forespørgsler mislykkes

Returnerer:

• QueryResult: Indeholder resultaterne for eksplosionsradius

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

Udfør centralitetsanalyse på grafen.

Parametre:

• participating_source_node_labels (Valgfri[List[str]]): Kildenodenavne
• participating_target_node_labels (Valgfri[List[str]]): Destinationsnodenavne
• participating_edge_labels (Valgfri[List[str]]): Edge-mærkater, der skal gennemgås
• threshold (int): Mindste centralitetsscore (standard: 3); skal være ikke-negativ
• centrality_type (CentralityType): CentralityType.Node eller CentralityType.Edge (standard: None, går tilbage til CentralityType.Node)
• max_paths (int): Det maksimale antal stier, der skal overvejes (standard: 1000000; 0 = alle stier), skal være ikke-negative
• is_directional (bool): Om kanterne er retningsbestemt (standard: True)
• min_hop_count (int): Minimumhop (standard: 1); skal være ≥ 1
• max_hop_count (int): Maksimumhop (standard: 4); skal være ≥ min_hop_count
• shortest_path (bool): Returner kun korteste stier (standard: False)
• max_results (int): Maksimalt antal resultater (standard: 500); skal være ≥ 1

Rejser:

• ValueError: Hvis threshold < 0, max_paths < 0, min_hop_count < 1, max_hop_count < min_hop_counteller max_results < 1
• RuntimeError: Hvis klientinitialisering eller udførelse af forespørgsler mislykkes

Returnerer:

• QueryResult: Indeholder centralitetsmålepunkterne

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

Udfør rangerede analyser på grafen.

Parametre:

• rank_property_name (str): Egenskabsnavn, der skal bruges til rangering (valideret på kørselstidspunktet. Skal angives, når der ikke bruges query_input)
• threshold (int): Returner kun stier over denne vægt (standard: 0); skal være ikke-negative
• max_paths (int): Det maksimale antal stier, der skal overvejes (standard: 1000000; 0 = alle stier), skal være ikke-negative
• decay_factor (flydende): Rangordnet henfald pr. trin; 2 betyder halvering (standard: 1); skal være ikke-negativ
• is_directional (bool): Om kanterne er retningsbestemt (standard: True)
• min_hop_count (int): Minimumhop (standard: 1); skal være ≥ 1
• max_hop_count (int): Maksimumhop (standard: 4); skal være ≥ min_hop_count
• shortest_path (bool): Returner kun korteste stier (standard: False)
• max_results (int): Maksimalt antal resultater (standard: 500); skal være ≥ 1

Rejser:

• ValueError: Hvis rank_property_name mangler, , threshold < 0max_paths < 0, decay_factor < 0, min_hop_count < 1, max_hop_count < min_hop_count, ellermax_results < 1
• RuntimeError: Hvis klientinitialisering eller udførelse af forespørgsler mislykkes

Returnerer:

• QueryResult: Indeholder de rangerede noder/kanter

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

Konvertér hele grafen til GraphFrame. Bruger spec-data, når de er tilgængelige. læser fra søtabeller ellers.

Parametre:

• column_mapping (Dict[str, str], valgfrit): Brugerdefineret kolonnetilknytning

Returnerer:

• GraphFrame: GraphFrame-objekt med alle knudepunkter og kanter

Eksempel:

gf = graph.to_graphframe()

show

def show() -> None

Vis grafoplysninger. Uddelegerer til spec.show() til avanceret visning, når en specifikation er vedhæftet. Ellers udskrives minimale oplysninger.

show_schema

def show_schema() -> None

Vis grafskema. Delegerer til spec.show_schema() , når en specifikation er vedhæftet. Udskriver en meddelelse, der angiver, at der ellers ikke er noget tilgængeligt skema.

publish (ny i v0.3.3)

def publish() -> Graph

Registrer grafen med API'en, så den kan forespørges. Kald dette efter Graph.prepare() (eller på en hvilken som helst Graph , der har en specifikation tilknyttet) for at publicere grafforekomsten.

Returnerer:

• Graph: Selv for metodekæde

Rejser:

• ValueError: Hvis der ikke er knyttet en specifikation, eller hvis der mangler en kontekst
• RuntimeError: Hvis publiceringen mislykkes

Eksempel:

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

BuildStatus

Dataclass, der indeholder metadata fra en Graph.build() handling.

Felter

Byggestier

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")

Node Builders

NodeBuilderInitial

Starttilstand for nodegenerator: Kun tilgængelige datakildemetoder.

Konstruktør

NodeBuilderInitial(alias: str, graph_builder: GraphSpecBuilder)

Bemærk: Oprettes typisk via GraphSpecBuilder.add_node(), ikke direkte instantieret.

Metoder

from_table

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

Angiv tabel som datakilde med intelligent databaseopløsning.

Parametre:

• table_name (str): Navnet på tabellen (påkrævet)
• database (str, valgfrit): Eksplicit databasenavn (tilsidesætter standardkonteksten)

Returnerer:

• NodeBuilderSourceSet: Generator til yderligere konfiguration

Rejser:

• ValueError: Hvis tabellen ikke blev fundet, eller der blev fundet flere modstridende tabeller

Databaseløsningsrækkefølge:

1. Eksplicit database parameter (højeste prioritet)
2. ExecutionContext.default_database
3. Søg i alle databaser (med konfliktregistrering)

Eksempel:

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

from_dataframe

def from_dataframe(dataframe: DataFrame) -> NodeBuilderSourceSet

Angiv Spark DataFrame som datakilde.

Parametre:

• dataframe (DataFrame): Spark DataFrame

Returnerer:

• NodeBuilderSourceSet: Generator til yderligere konfiguration

Eksempel:

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

NodeBuilderSourceSet

Node builder, når datakilden er angivet: tilgængelige konfigurationsmetoder.

Konstruktør

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

Bemærk: Oprettet internt af NodeBuilderInitial-kildemetoder.

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

Anvend filtrering af tidsinterval på nodens datakilde.

Parametre:

• time_column (str): Kolonnenavn, der indeholder tidsstempeldata (påkrævet)
• start_time (str eller datetime, valgfrit): Startdato ('10/20/25', '2025-10-20' eller datetime-objekt)
• end_time (str eller datetime, valgfrit): Slutdato (samme formater som start_time)
• lookback_hours (flydende, valgfrit): Timer, der skal kigges tilbage fra nu

Returnerer:

• NodeBuilderSourceSet: Selv for metodekæde

Rejser:

• ValueError: Hvis klokkeslætskolonnen ikke blev fundet i kildeskemaet

Tidsintervallogik:

1. Hvis start_time og end_time angivet: Brug dem direkte
2. Hvis der kun er angivet lookback_hours: end=now, skal du starte=now-lookback_hours
3. Hvis der ikke er angivet noget: ingen tidsfiltrering
4. Hvis start/slut OG lookback_hours: start/slut 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

Angiv nodenavn (standard er alias, hvis det ikke kaldes).

Parametre:

• label (str): Nodenavn

Returnerer:

• NodeBuilderSourceSet: Selv for metodekæde

Rejser:

• ValueError: Hvis navnet allerede er angivet

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 den påkrævede nøgle og visningsangivelse.

Parametre:

• *columns (str): Kolonnenavne, der skal medtages (mindst ét påkrævet)
• key (str): Det kolonnenavn, der skal markeres som nøgle (obligatorisk, skal være i kolonner)
• display (str): Det kolonnenavn, der skal markeres som visningsværdi (obligatorisk, skal være i kolonner, kan være det samme som nøglen)

Returnerer:

• NodeBuilderSourceSet: Selv for metodekæde

Rejser:

• ValueError: Hvis valideringen mislykkes (dubletkolonner, manglende nøgle/visning osv.)

Noter:

• Egenskaber bygges automatisk ud fra kolonnetyper

• Kolonnen med tidsfilteret tilføjes automatisk, hvis det er angivet

• Egenskabstyper udledes automatisk fra kildeskema

• Se Begrænsninger

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

Afslut denne node, og begynd at oprette en anden node.

Parametre:

• alias (str): Alias for den nye node

Returnerer:

• NodeBuilderInitial, ny nodegenerator

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

Afslut denne node, og begynd at oprette en kant.

Parametre:

• alias (str): Alias for kanten

Returnerer:

• EdgeBuilderInitial, ny edge builder

Eksempel:

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

done

def done() -> GraphSpec

Afslut denne node, og udfyld grafspecifikationen.

Returnerer:

• GraphSpec: Fuldstændig grafspecifikation

Eksempel:

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

Edge Builders

EdgeBuilderInitial

Starttilstand for Edge Builder: Kun tilgængelige datakildemetoder.

Konstruktør

EdgeBuilderInitial(alias: str, graph_builder: GraphSpecBuilder)

Bemærk: Oprettes typisk via GraphSpecBuilder.add_edge(), ikke direkte instantieret.

Metoder

from_table

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

Angiv tabel som datakilde med intelligent databaseopløsning.

Parametre:

• table_name (str): Navnet på tabellen (påkrævet)
• database (str, valgfrit): Eksplicit databasenavn

Returnerer:

• EdgeBuilderSourceSet: Generator til yderligere konfiguration

Rejser:

• ValueError: Hvis tabellen ikke blev fundet, eller der blev fundet flere modstridende tabeller

Eksempel:

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

from_dataframe

def from_dataframe(dataframe: DataFrame) -> EdgeBuilderSourceSet

Angiv Spark DataFrame som datakilde.

Parametre:

• dataframe (DataFrame): Spark DataFrame

Returnerer:

• EdgeBuilderSourceSet: Generator til yderligere konfiguration

Eksempel:

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

EdgeBuilderSourceSet

Edge Builder, når datakilden er angivet: tilgængelige konfigurationsmetoder.

Konstruktør

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

Bemærk: Oprettet internt af EdgeBuilderInitial-kildemetoder.

Metoder

with_label

def with_label(label: str) -> EdgeBuilderSourceSet

Angiv kantrelationstype/-navn (som standard alias, hvis det ikke kaldes).

Parametre:

• label (str): Edge-navn

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekæde

Rejser:

• ValueError: Hvis navnet allerede er angivet

Eksempel:

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

edge_label

def edge_label(label: str) -> EdgeBuilderSourceSet

Angiv kantrelationstype/-navn (som standard alias, hvis det ikke kaldes).

Parametre:

• label (str): Edge-navn

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekæde

Rejser:

• ValueError: Hvis navnet allerede er angivet

Eksempel:

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

source

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

Angiv kildenoden med id-kolonne og navn.

Parametre:

• id_column (str): Kolonnenavn, der indeholder kildenode-id
• node_type (str): Kildenodenavn

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekæde

Rejser:

• ValueError: Hvis kilden allerede er angivet

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

Angiv destinationsnoden med id-kolonne og navn.

Parametre:

• id_column (str): Kolonnenavn, der indeholder destinationsnodens id
• node_type (str): Destinationsnodenavn

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekæde

Rejser:

• ValueError: Hvis destinationen allerede er angivet

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

Anvend filtrering af tidsinterval på kantens datakilde.

Parametre:

• time_column (str): Kolonnenavn, der indeholder tidsstempeldata (påkrævet)
• start_time (str eller datetime, valgfrit): Startdato
• end_time (str eller datetime, valgfrit): Slutdato
• lookback_hours (flydende, valgfrit): Timer, der skal kigges tilbage fra nu

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekæde

Rejser:

• ValueError: Hvis klokkeslætskolonnen ikke blev fundet i kildeskemaet

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 den påkrævede nøgle og visningsangivelse.

Parametre:

• *columns (str): Kolonnenavne, der skal medtages (mindst ét påkrævet)
• key (str): Det kolonnenavn, der skal markeres som nøgle (obligatorisk, skal være i kolonner)
• display (str): Det kolonnenavn, der skal markeres som visningsværdi (obligatorisk, skal være i kolonner)

Returnerer:

• EdgeBuilderSourceSet: Selv for metodekæde

Rejser:

• ValueError: Hvis valideringen 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

Afslut denne kant, og begynd at oprette en node.

Parametre:

• alias (str): Alias for den nye node

Returnerer:

• NodeBuilderInitial, ny nodegenerator

add_edge

def add_edge(alias: str) -> EdgeBuilderInitial

Afslut denne kant, og begynd at bygge en anden kant.

Parametre:

• alias (str): Alias for den nye kant

Returnerer:

• EdgeBuilderInitial, ny edge builder

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

Afslut denne kant, og udfyld grafspecifikationen.

Returnerer:

• GraphSpec: Fuldstændig grafspecifikation

Skemaklasser

GraphDefinitionReference

Reference til en grafdefinition med navn og version.

Konstruktør

GraphDefinitionReference(
    fully_qualified_name: str,
    version: str
)

Parametre:

• fully_qualified_name (str): Fuldt kvalificeret navn på den graf, der henvises til
• version (str): Version af den graf, der henvises til

Rejser:

• ValueError: Hvis fully_qualified_name eller version er tom

Metoder

to_dict

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

Serialiser til ordbog.

Returnerer:

• Dict[str, Any], serialiseret reference

Ejendom

Egenskabsdefinition med grænseflade, der er typesikker.

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
)

Parametre:

• name (str): Egenskabsnavn
• property_type (PropertyType): Egenskabsdatatype
• is_non_null (bool, default=False): Om egenskaben er påkrævet
• description (str, default=""): Beskrivelse af egenskab
• is_key (bool, default=False): Om egenskaben er en nøgle
• is_display_value (bool, default=False): Om egenskaben er visningsværdi
• is_internal (bool, default=False): Om egenskaben er intern

Rejser:

• 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

Opret en nøgleegenskab med almindelige indstillinger (is_key=Sand, is_display_value=Sand).

display

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

Opret en visningsværdiegenskab (is_display_value=Sand).

Metoder

describe

def describe(text: str) -> Property

Tilføj beskrivelsen flydende.

Parametre:

• text (str): Beskrivelsestekst

Returnerer:

• Property: Selv for metodekæde

to_dict

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

Serialiser egenskaben til ordbogen med anmærkningsnøgler med @-præfiks.

Returnerer:

• Dict[str, Any], serialiseret egenskab

to_gql

def to_gql() -> str

Generér GQL-egenskabsdefinition.

Returnerer:

• str: GQL-strengrepræsentation

EdgeNode

Nodereference, der bruges i edge-definitioner.

Konstruktør

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

Parametre:

• alias (str, valgfrit): Nodealias (automatisk indstillet til første etiket, hvis Ingen eller tom)
• labels (List[str]): Nodenavne (mindst én påkrævet)

Rejser:

• ValueError: Hvis listen over etiketter er tom
• TypeError: Hvis navne ikke er strenge

Automatisk mutation:

• Hvis aliasset er Ingen eller tomt, angives det til det første navn

Metoder

to_dict

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

Serialiser til ordbog.

Returnerer:

• Dict[str, Any]: Serialiseret kantnodereference

Node

Nodedefinition med typesikker grænseflade.

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
)

Parametre:

• alias (str, default=""): Nodealias (automatisk indstillet til første etiket, hvis den er tom)
• labels (List[str]): Nodenavne (mindst én påkrævet)
• implies_labels (List[str], default=[]): Implicitte navne
• properties (List[Property], default=[]): Nodeegenskaber
• description (str, default=""): Nodebeskrivelse
• entity_group (str, default=""): Navn på objektgruppe
• dynamic_labels (bool, default=False): Om noden har dynamiske mærkater
• abstract_edge_aliases (bool, default=False): Om noden bruger abstrakte kantaliasser

Rejser:

• ValueError: Hvis valideringen mislykkes (ingen navne, ingen nøgleegenskab, ingen visningsegenskab osv.)

Automatisk mutation:

• Hvis aliasset er tomt, angives det til det første navn
• Hvis entity_group er tom, angives den til den primære etiket

Metoder

get_primary_label

def get_primary_label() -> Optional[str]

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

Returnerer:

• str eller None: Primær etiket eller Ingen, hvis der ikke er nogen navne

get_entity_group_name

def get_entity_group_name() -> str

Hent navnet på objektgruppen, eller gå tilbage til det primære navn.

Returnerer:

• str, navn på objektgruppe

get_primary_key_property_name

def get_primary_key_property_name() -> Optional[str]

Hent navnet på egenskaben for den primære nøgle.

Returnerer:

• str eller None: Navn på egenskab for primær nøgle

get_properties

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

Få egenskaber som en ordbog, så du nemt kan få adgang til dem.

Returnerer:

• Dict[str, Property]: Egenskaber med nøgle efter navn

get_property

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

Hent en bestemt egenskab efter navn.

Parametre:

• name (str): Egenskabsnavn

Returnerer:

• Property eller None: Egenskab, hvis den blev fundet

add_property

def add_property(prop: Property) -> None

Føj en egenskab til denne node.

Parametre:

• prop (Egenskab): Egenskab, der skal tilføjes

Rejser:

• ValueError: Hvis egenskabsnavnet er duplikeret

is_dynamically_labeled

def is_dynamically_labeled() -> bool

Kontrollér, om noden har dynamiske navne.

Returnerer:

• bool: Sand, hvis dynamiske mærkater er aktiveret

is_abstract_edge_node_aliases

def is_abstract_edge_node_aliases() -> bool

Kontrollér, om noden bruger abstrakte kantnodealiasser.

Returnerer:

• bool: Sand, hvis abstrakte kantaliasser er aktiveret

describe

def describe(text: str) -> Node

Tilføj beskrivelsen flydende.

Parametre:

• text (str): Beskrivelsestekst

Returnerer:

• Node: Selv for metodekæde

to_dict

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

Serialiser noden til ordbogen.

Returnerer:

• Dict[str, Any], serialiseret node

to_gql

def to_gql() -> str

Generér GQL-nodedefinition.

Returnerer:

• str: GQL-strengrepræsentation

Rejser:

• ValueError: Hvis noden mangler obligatoriske felter til GQL

Klassemetoder

create

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

Opret en node med alle obligatoriske felter.

Parametre:

• alias (str): Nodealias
• labels (List[str]): Nodenavne
• properties (List[Property]): Nodeegenskaber
• description (str, default=""): Nodebeskrivelse
• entity_group (str, default=""): Navn på objektgruppe

Returnerer:

• Node, ny nodeforekomst

Kant

Edge-definition med typesikker grænseflade.

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
)

Parametre:

• relationship_type (str): Edge-relationstype (f.eks. "FØLGER", "OWNS")
• source_node_label (str): Kildenodenavn
• target_node_label (str): Destinationsnodenavn
• direction (EdgeDirection, default=DIRECTED_RIGHT): Kantretning
• properties (List[Property], default=[]): Edge-egenskaber
• description (str, default=""): Edge-beskrivelse
• entity_group (str, default=""): Navn på objektgruppe
• dynamic_type (bool, default=False): Om kant har dynamisk type

Rejser:

• ValueError: Hvis valideringen mislykkes

Automatisk mutation:

• labels udfyldes automatisk med [relationship_type]
• Hvis entity_group er tom, angives den til relationship_type

Egenskaber

edge_type

def edge_type() -> str

Alias for bagudkompatibilitet for relationship_type.

Returnerer:

• str, relationstype

Metoder

get_entity_group_name

def get_entity_group_name() -> str

Hent navnet på objektgruppen, eller gå tilbage til relationstypen.

Returnerer:

• str, navn på objektgruppe

is_dynamic_type

def is_dynamic_type() -> bool

Kontrollér, om kant har dynamisk type.

Returnerer:

• bool: Sand, hvis dynamisk type

add_property

def add_property(edge_property: Property) -> None

Føj en egenskab til denne kant.

Parametre:

• edge_property (Egenskab): Egenskab, der skal tilføjes

describe

def describe(text: str) -> Edge

Tilføj beskrivelsen flydende.

Parametre:

• text (str): Beskrivelsestekst

Returnerer:

• Edge: Selv for metodekæde

to_dict

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

Serialiser kant til ordbog.

Returnerer:

• Dict[str, Any], serialiseret kant

to_gql

def to_gql() -> str

Generér GQL-edgedefinition.

Returnerer:

• str: GQL-strengrepræsentation

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

Opret en kant med alle obligatoriske felter.

Parametre:

• relationship_type (str): Edge-relationstype
• source_node_label (str): Kildenodenavn
• target_node_label (str): Destinationsnodenavn
• properties (List[Property], valgfrit): Edge-egenskaber
• description (str, default=""): Edge-beskrivelse
• entity_group (str, default=""): Navn på objektgruppe

Returnerer:

• Edge: Ny edge-forekomst

GraphSchema

Grafskemadefinition med typesikker grænseflade.

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 = ""
)

Parametre:

• name (str): Diagramskemanavn
• nodes (List[Node], default=[]): Nodedefinitioner
• edges (List[Edge], default=[]): Edge-definitioner
• base_graphs (List[GraphSchema], default=[]): Basisgrafskemaer
• description (str, default=""): Skemabeskrivelse
• version (str, default="1.0"): Skemaversion
• fully_qualified_name (str, default=""): Fuldt kvalificeret navn
• namespace (str, default=""): Navneområde

Rejser:

• ValueError: Hvis valideringen mislykkes (dubletaliasser, kanter refererer til ikke-eksisterende noder osv.)

Metoder

get_fully_qualified_name

def get_fully_qualified_name() -> str

Hent det fuldt kvalificerede navn.

Returnerer:

• str, fuldt kvalificeret navn

get_namespace

def get_namespace() -> str

Hent navneområde fra fuldt kvalificeret navn, eller returner standard.

Returnerer:

• str:Navneområde

get_version

def get_version() -> str

Hent version.

Returnerer:

• str, versionsstreng

get_node

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

Hent node efter navn eller alias.

Parametre:

• label_or_alias (str): Nodenavn eller -alias

Returnerer:

• Node or None: Node, hvis fundet

get_edge

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

Hent kant efter navn/type.

Parametre:

• name (str): Edge-relationstype

Returnerer:

• Edge eller None: Edge, hvis den findes

add_node

def add_node(node: Node) -> None

Føj en node til denne graf.

Parametre:

• node (Node): Node, der skal tilføjes

Rejser:

• ValueError: Hvis nodealiaset er dublet

add_edge

def add_edge(edge: Edge) -> None

Føj en kant til denne graf.

Parametre:

• edge (Edge): Kant, der skal tilføjes

Rejser:

• ValueError: Hvis kanttypen er duplikeret

include_graph

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

Tilføj en graf include (flydende API).

Parametre:

• fully_qualified_name (str): Fuldt kvalificeret navn på grafen, der skal medtages
• version (str): Version af graf, der skal medtages

Returnerer:

• GraphSchema: Selv for metodekæde

get_included_graph_references

def get_included_graph_references() -> List[GraphDefinitionReference]

Hent en liste over inkluderede grafreferencer.

Returnerer:

• List[GraphDefinitionReference]: Liste over grafdefinitionsreferencer

describe

def describe(text: str) -> GraphSchema

Tilføj beskrivelsen flydende.

Parametre:

• text (str): Beskrivelsestekst

Returnerer:

• GraphSchema: Selv for metodekæde

to_dict

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

Serialiser skema til ordbog.

Returnerer:

• Dict[str, Any], serialiseret skema

to_json

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

Generér JSON-repræsentation.

Parametre:

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

Returnerer:

• str, JSON-streng

to_gql

def to_gql() -> str

Generér GQL-skemadefinition.

Returnerer:

• str: GQL-strengrepræsentation

Klassemetoder

create

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

Opret et grafskema med alle obligatoriske felter.

Parametre:

• name (str): Diagramskemanavn
• nodes (List[Node], valgfrit): Nodedefinitioner
• edges (List[Edge], valgfrit): Edge-definitioner
• description (str, default=""): Skemabeskrivelse
• version (str, default="1.0"): Skemaversion

Returnerer:

• GraphSchema: Ny diagramskemaforekomst

Forespørgselsinputklasser

Dataklassificeringer, der repræsenterer inputparametre for foruddefinerede grafforespørgsler.

QueryInputBase

Basisklasse for alle forespørgselsinputparametre.

Metoder

to_json_payload

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

Konvertér inputparametrene til en ordbog til INDSENDELSE AF API.

Returnerer:

• Dict[str, Any]: Ordbogsrepræsentation af inputparametrene

validate

def validate() -> None

Valider inputparametrene.

Rejser:

• ValueError: Hvis inputparametrene er ugyldige

ReachabilityQueryInput

Inputparametre for en forespørgsel om rækkevidde mellem kilde- og destinationsnoder. Arver fra ReachabilityQueryInputBase , som nedarver fra QueryInputBase.

Felter

Validering:

• source_property_value er påkrævet
• target_property_value er påkrævet

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

Inputparametre for en k-hop-forespørgsel fra en given kildenode. Arver fra ReachabilityQueryInputBase.

Arver alle felter fra ReachabilityQueryInput.

Validering:

• Der skal angives mindst én af source_property_value eller target_property_value

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

Inputparametre for en forespørgsel med en blast radius fra kilde til destinationsnoder. Arver fra ReachabilityQueryInputBase.

Arver alle felter fra ReachabilityQueryInputmed følgende obligatoriske felter:

Validering:

• source_property_value er påkrævet
• target_property_value er påkrævet

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

Inputparametre for en centralitetsanalyseforespørgsel. Arver fra QueryInputBase.

CentralityType-optælling

Felter

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

Inputparametre for en rangeret analyseforespørgsel. Arver fra QueryInputBase.

Felter

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
))

Forespørgselsresultater

Forespørgselsresultat

Resultatet af en grafforespørgsel med doven DataFrame-adgang.

Konstruktør

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

Parametre:

• raw_response (Dict[str, Any]): Raw API-svarordbog
• graph (Graf): Reference til overordnet graf

Bemærk: Oprettes typisk af Graph.query(), ikke direkte instantieret.

Metoder

to_dataframe

def to_dataframe() -> DataFrame

Konverterer forespørgselsresultatet til en Spark DataFrame.

Returnerer:

• DataFrame, forespørgselsresultat som Spark DataFrame

Rejser:

• 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]

Hent afsnittet RawData fra svaret.

Returnerer:

• Dict[str, Any]: Ordbog med rå metadata eller tom dikt, hvis den ikke findes

Eksempel:

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

show

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

Vis forespørgselsresultatet i forskellige formater.

Parametre:

• format (str, default="visual"): Outputformat
  • "table", komplette DataFrame-tabeller (alle kolonner)
  • "visual": Interaktiv grafvisualisering med VSC-plug-in
  • "all": Vis alle formater

Rejser:

• ValueError: Hvis format ikke er en af de understøttede værdier

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

Komplet eksempel (anbefalet – 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()

Noter om designmønstre

Flydende API

Alle udviklere understøtter sammenkædning af metoder for læsbare, deklarative grafdefinitioner:

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

Foreningsskemaer

Flere kanter med det samme alias foreningsopereres automatisk med flettede egenskaber:

# 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")

Automatisk konfiguration

Mange felter har fornuftige standarder:

• Node-/kantnavne bruger som standard deres aliasser
• Egenskaber udledes automatisk fra kildeskemaer
• Objektgrupper bruger som standard primære navne/relationstyper

Doven evaluering

DataFrames og ressourcer indlæses dovent og cachelagres:

• graph_spec.nodes og graph_spec.edges indlæses ved første adgang
• Forespørgselsresultater opretter kun datarammer, når der anmodes om det

Relateret indhold

• Oversigt over brugerdefinerede grafer
• Opret brugerdefinerede grafer