Graph Builderin ohjelmointirajapinnan viittaus (esikatselu)

sentinel_graph luokan avulla voit käsitellä Microsoft Sentinel kaaviota, jolloin voit määrittää kaavion rakenteen, muuntaa tietoja Microsoft Sentinel Data Lake -tallennustilasta solmuiksi ja reuneiksi, julkaista kaavion, kyselykaavion ja suorittaa kehittyneitä kaavioalgoritmeja. Tämä luokka on suunniteltu toimimaan Jupyter-muistikirjojen Spark-istuntojen kanssa, jotka suoritetaan Microsoft Sentinel spark-käsittelyssä.

GraphSpecBuilder

GraphSpecBuilder-luokka tarjoaa sujuvan muodostimen kaaviomääritysten luomiseen tietoputkilla ja rakenteen integroinnilla.

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

# Recommended
from sentinel_graph import GraphSpecBuilder

Rakentaja

GraphSpecBuilder(context: ExecutionContext)

Parametrit:

• context (ExecutionContext): Suorituskonteksti, joka sisältää Spark-istunnon ja -määritykset

Herättää:

• ValueError: Jos konteksti on Ei mitään tai kaavion nimeä ei voida määrittää

Staattiset menetelmät

start

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

Määritä uusi sujuva kaavion muodostin.

Parametrit:

• context (ExecutionContext, valinnainen): ExecutionContext-esiintymä. Jos ei mitään, käyttää oletuskontekstia.

Palauttaa:

• GraphSpecBuilder: Uusi muodostimen esiintymä

Esimerkki:

builder = GraphSpecBuilder.start(context=context)

Esiintymämenetelmät

add_node

def add_node(alias: str) -> NodeBuilderInitial

Aloita solmumäärityksen luominen.

Parametrit:

• alias (str): Tämän solmun yksilöllinen tunniste kaaviossa

Palauttaa:

• NodeBuilderInitial: Solmun muodostin alkutilassa

Esimerkki:

builder.add_node("user")

add_edge

def add_edge(alias: str) -> EdgeBuilderInitial

Aloita reunamäärityksen luominen.

Parametrit:

• alias (str): Tämän reunan tunnus kaavion sisällä (voidaan jakaa useille reunuksille)

Palauttaa:

• EdgeBuilderInitial: Edgen muodostin alkutilassa

Esimerkki:

builder.add_edge("accessed")

done

def done() -> GraphSpec

Viimeistele kaavion määritys ja palauta GraphSpec-esiintymä.

Palauttaa:

• GraphSpec: Täydennä kaavion määritys tietoputkella ja rakenteella

Herättää:

• ValueError: Jos kaaviossa ei ole solmuja tai reunoja tai jos vahvistus epäonnistuu

Esimerkki:

graph_spec = builder.done()

GraphSpec

Kaaviomääritys, jossa on tietoputki, rakenne ja näyttöominaisuudet.

Rakentaja

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

Parametrit:

• name (str): Kaavion nimi
• context (ExecutionContext): Suorituskonteksti
• graph_schema (GraphSchema): Graph-rakenteen määritys
• etl_pipeline (ETLPipeline, valinnainen): Kaavion valmistelun tietoputki

Ominaisuudet

nodes

def nodes() -> DataFrame

Nouda solmut DataFrame (lazy, cached). Määrittää lähteen automaattisesti tietoputkesta tai lake-taulukosta.

Palauttaa:

• DataFrame: Spark DataFrame, joka sisältää kaikki solmut

Herättää:

• ValueError: Jos kontekstia puuttuu tai DataFrame-kehyksia ei voi ladata

edges

def edges() -> DataFrame

Hae reunat DataFrame (lazy, cached). Määrittää lähteen automaattisesti tietoputkesta tai lake-taulukosta.

Palauttaa:

• DataFrame: Spark DataFrame sisältää kaikki reunat

Herättää:

• ValueError: Jos kontekstia puuttuu tai DataFrame-kehyksia ei voi ladata

Menetelmiä

build_graph_with_data

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

Suorita tietoputki ja julkaise kaavio. Kutsuu Graph.build(self)sisäisesti palautettua Graph, ja palauttaa taaksepäin yhteensopivan sanaston.

Palauttaa:

• Dict[str, Any]: Sanasto, joka sisältää:
  • etl_result: Tietojen valmistelun tulokset
  • api_result: Julkaise tulokset (jos onnistut)
  • api_error: Virhemerkkijono (jos julkaiseminen epäonnistui)
  • instance_name: Kaavioesiintymän nimi
  • status: "published" tai "prepared"

Esimerkki:

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

get_schema

def get_schema() -> GraphSchema

Hae kaavion rakenne.

Palauttaa:

• GraphSchema: Kaavion rakenteen määritys

get_pipeline

def get_pipeline() -> Optional[ETLPipeline]

Nouda tietoputki (ei mitään aiemmin luoduissa kaavioissa).

Palauttaa:

• ETLPipeline tai None: Tietoputki, jos se on käytettävissä

to_graphframe

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

Muunna koko kaavio GraphFrameksi kaavioalgoritmien suorittamista varten. Toimii vain paikallisissa tiedoissa (tietoputkesta tai järven taulukosta).

Parametrit:

• column_mapping (Dict[str, str], valinnainen): Mukautettujen sarakkeiden yhdistämismääritys avaimilla:
  • "id": Kärkipisteen tunnussarakkeen nimi
  • "source_id": Edge-lähdetunnussarakkeen nimi
  • "target_id": Edgen kohdetunnussarakkeen nimi

Palauttaa:

• GraphFrame: GraphFrame-objekti, jossa on kaikki kärkipisteet ja reunat

Herättää:

• ValueError: Jos ExecutionContext ei ole käytettävissä

Esimerkki:

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

show

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

Näytä kaavion tiedot eri muodoissa.

Parametrit:

• limit (kokonaislukema= 100): Näytettäviä solmuja/reunoja enintään
• viz_format (str, default="visual"): Tulostemuoto
  • "table": Täydet DataFrame-taulukot (kaikki sarakkeet)
  • "visual": Vuorovaikutteinen kaaviovisualisointi
  • "all": Näytä kaikki muodot

Herättää:

• ValueError: Jos muoto ei ole yksi tuetuista arvoista

Esimerkki:

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

show_schema

def show_schema() -> None

Näytä kaavion rakenne vuorovaikutteisena kaaviovisualisointina.

Esimerkki:

spec.show_schema()

Kaavio

Kyselettävä kaavioesiintymä. Luotu käyttämällä Graph.get() (aiemmin luotua kaaviota) tai Graph.build() (kohteesta GraphSpec).

Rakentaja

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

Parametrit:

• name (str): Kaavion nimi
• context (ExecutionContext): Suorituskonteksti
• spec (GraphSpec, valinnainen): Liitetty kaaviomääritys (määrittänyt Graph.build())
• build_status (BuildStatus, valinnainen): Koontiversion tuloksen metatiedot (määrittänyt Graph.build())

Herättää:

• ValueError: Jos ExecutionContext on Ei mitään

Staattiset menetelmät

get

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

Hae kaavioesiintymä olemassa olevasta kaaviosta. Palautetut Graph -mittarit ovat spec=None ja build_status=None.

Parametrit:

• name (str): Kaavioesiintymän nimi
• context (ExecutionContext, valinnainen): Suorituskonteksti (oletusarvo on ExecutionContext.default())

Palauttaa:

• Graph: Kaavioesiintymä

Herättää:

• ValueError: Jos kaavion nimi on tyhjä tai kaavioesiintymää ei ole olemassa

Esimerkki:

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

prepare

Graph.prepare(spec: GraphSpec) -> Graph

Suorita tietojen valmisteluvaihe toiminnolle ilmanGraphSpec julkaisemista. Tämän jälkeen voit publish() rekisteröidä kaavion ja tehdä siitä kyselevän.

Parametrit:

• spec (GraphSpec): Graph-määritys, joka valmistellaan

Palauttaa:

• Graph: Kaavioesiintymä, johon on spec liitetty ja build_status.status == "prepared"

Herättää:

• ValueError: Jos määrityksellä ei ole tietoputkea tai suorituskontekstia
• RuntimeError: Jos tietoputken suorittaminen epäonnistuu

Esimerkki:

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

Luo kaavio kohteesta GraphSpec valmistelemalla tiedot ja julkaisemalla. Kutsuu Graph.prepare(spec) sisäisesti ja yrittää graph.publish()sitten . Toisin kuin kutsumalla näitä kahta menetelmää erikseen, julkaisuvirheet jäävät kiinni – palautetussa kaaviossa on ja build_status.api_error se on build_status.status == "prepared" määritetty nostamisen sijaan.

Parametrit:

• spec (GraphSpec): Graph-määritys, josta muodostettava

Palauttaa:

• Graph: Kaavioesiintymä, johon on spec liitetty ja build_status täytetty

Herättää:

• ValueError: Jos määrityksellä ei ole tietoputkea tai suorituskontekstia
• RuntimeError: Jos tietoputken suorittaminen epäonnistuu

Esimerkki:

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

Ominaisuudet

nodes

def nodes() -> Optional[DataFrame]

Nouda solmut DataFrame. Edustajat kohteeseen self.spec.nodes , kun määritys on liitetty; palauttaa muussa tapauksessa arvon None .

edges

def edges() -> Optional[DataFrame]

Hae reunat DataFrame. Edustajat kohteeseen self.spec.edges , kun määritys on liitetty; palauttaa muussa tapauksessa arvon None .

schema

def schema() -> Optional[GraphSchema]

Hae kaaviorakenne. Edustajat kohteeseen self.spec.get_schema() , kun määritys on liitetty; palauttaa muussa tapauksessa arvon None .

Menetelmiä

query

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

Suorita kysely kaavioesiintymälle GQL:n avulla.

Parametrit:

• query_string (str): Graph-kyselymerkkijono (GQL-kieli)
• query_language (str, default="GQL"): Kyselyn kieli

Palauttaa:

• QueryResult: Objekti, joka sisältää solmuja, reunoja ja metatietoja

Herättää:

• ValueError: Jos ExecutionContext- tai Spark-istunto puuttuu
• RuntimeError: Jos asiakkaan alustus tai kyselyn suorittaminen epäonnistuu

Esimerkki:

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

[! HUOMAUTUS] reachability(query_input=ReachabilityQueryInput(...)) hyväksytään edelleen, mutta se lähetetään DeprecationWarning , ja se poistetaan tulevassa versiossa.

Suorita tavoitettavuusanalyysi lähde- ja kohdesolmujen välillä.

Parametrit:

• source_property_value (str): Lähdeominaisuuden vastaava arvo (vahvistettu suorituksen aikana. On annettava, kun käytössä ei ole query_input)
• target_property_value (str): Kohdeominaisuuden vastaava arvo (vahvistettu suorituksen aikana. On annettava, kun käytössä ei ole query_input)
• source_property (Valinnainen[str]): Lähdesolmujen suodattamiseen käytetyn ominaisuuden nimi
• participating_source_node_labels (Valinnainen[Luettelo[str]]): Lähteinä otettavat solmun selitteet
• target_property (Valinnainen[str]): Kohdesolmujen suodattamiseen käytetyn ominaisuuden nimi
• participating_target_node_labels (Valinnainen[Luettelo[str]]): Tavoitteina otettavat solmun selitteet
• participating_edge_labels (Valinnainen[Luettelo[str]]): Läpikäytävät reunaotsikot
• is_directional (totuusarvo): Ovatko reunat suuntaisia (oletus: True)
• min_hop_count (kokonaisluku): Vähimmäissiirtymät (oletus: 1)
• max_hop_count (kokonaisluku): Suurin sallittu siirtymä (oletus: 4)
• shortest_path (totuusarvo): Palauta vain lyhyimmät polut (oletus: False)
• max_results (kokonaisluku): Tulosten enimmäismäärä (oletus: 500)

Herättää:

• ValueError: Jos source_property_value tai target_property_value puuttuu, , min_hop_count < 1, max_hop_count < min_hop_counttai max_results < 1
• RuntimeError: Jos asiakkaan alustus tai kyselyn suorittaminen epäonnistuu

Palauttaa:

• QueryResult: Sisältää tavoitettavuuspolut

Esimerkki:

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

Suorita k-hop-analyysi annetusta lähdesolmusta.

Parametrit:

• Sama kuin reachability

Validation:

• Vähintään yksi tai source_property_valuetarget_property_value on annettava

Herättää:

• ValueError: Jos ei anneta source_property_value tai target_property_value jos numeerisia rajoituksia ei rikota (sama kuin reachability)
• RuntimeError: Jos asiakkaan alustus tai kyselyn suorittaminen epäonnistuu

Palauttaa:

• QueryResult: Sisältää k-hop-tulokset

Esimerkki:

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

Suorita räjähdyssädeanalyysi lähdesolmusta kohdesolmuun.

Parametrit:

• source_property_value (str): Lähdesolmun tunnistava arvo (vahvistettu suorituksen aikana). On annettava, kun käytössä ei ole query_input)
• target_property_value (str): Kohdesolmun määrittävä arvo (vahvistettu suorituksen aikana). On annettava, kun käytössä ei ole query_input)
• Muut parametrit: sama kuin reachability

Herättää:

• ValueError: Jos source_property_value tai target_property_value puuttuu tai jos numeerisia rajoituksia rikotaan (sama kuin reachability)
• RuntimeError: Jos asiakkaan alustus tai kyselyn suorittaminen epäonnistuu

Palauttaa:

• QueryResult: Sisältää räjähdyssädetulokset

Esimerkki:

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

Suorita keskitetty analyysi kaaviolle.

Parametrit:

• participating_source_node_labels (Valinnainen[Luettelo[str]]): Lähdesolmun otsikot
• participating_target_node_labels (Valinnainen[Luettelo[str]]): Kohdesolmun otsikot
• participating_edge_labels (Valinnainen[Luettelo[str]]): Läpikäytävät reunaotsikot
• threshold (kokonaisluku): Keskisen vähimmäistuloksen (oletus: 3); on oltava ei-negatiivinen
• centrality_type (CentralityType): CentralityType.Node tai CentralityType.Edge (oletus: None, palauttaa kohteen CentralityType.Node)
• max_paths (kokonaisluku): Harkinnan enimmäispolut (oletus: 1000000; 0 = kaikki polut); ei saa olla negatiivinen
• is_directional (totuusarvo): Ovatko reunat suuntaisia (oletus: True)
• min_hop_count (kokonaisluku): Vähimmäissiirtymät (oletus: 1); on oltava ≥ 1
• max_hop_count (kokonaisluku): Suurin sallittu siirtymä (oletus: 4); on oltava ≥ min_hop_count
• shortest_path (totuusarvo): Palauta vain lyhyimmät polut (oletus: False)
• max_results (kokonaisluku): Tulosten enimmäismäärä (oletus: 500); on oltava ≥ 1

Herättää:

• ValueError: , threshold < 0, max_paths < 0, min_hop_count < 1, max_hop_count < min_hop_counttai max_results < 1
• RuntimeError: Jos asiakkaan alustus tai kyselyn suorittaminen epäonnistuu

Palauttaa:

• QueryResult: Sisältää keskisyysarvot

Esimerkki:

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

Suorita luokiteltu analyysi kaaviolle.

Parametrit:

• rank_property_name (str): Sijoituksessa käytettävän ominaisuuden nimi (vahvistettu suorituksen aikana). On annettava, kun käytössä ei ole query_input)
• threshold (kokonaisluku): Vain tätä painoa suuremmat paluupolut (oletus: 0); eivät saa olla negatiivisia
• max_paths (kokonaisluku): Harkinnan enimmäispolut (oletus: 1000000; 0 = kaikki polut); ei saa olla negatiivinen
• decay_factor (liukuluku): Sijoitus hajoaa askelta kohti; 2 tarkoittaa puolitusta (oletus: 1); ei saa olla negatiivinen
• is_directional (totuusarvo): Ovatko reunat suuntaisia (oletus: True)
• min_hop_count (kokonaisluku): Vähimmäissiirtymät (oletus: 1); on oltava ≥ 1
• max_hop_count (kokonaisluku): Suurin sallittu siirtymä (oletus: 4); on oltava ≥ min_hop_count
• shortest_path (totuusarvo): Palauta vain lyhyimmät polut (oletus: False)
• max_results (kokonaisluku): Tulosten enimmäismäärä (oletus: 500); on oltava ≥ 1

Herättää:

• ValueError: Jos rank_property_name puuttuu, , threshold < 0, max_paths < 0, decay_factor < 0, min_hop_count < 1, max_hop_count < min_hop_counttai max_results < 1
• RuntimeError: Jos asiakkaan alustus tai kyselyn suorittaminen epäonnistuu

Palauttaa:

• QueryResult: Sisältää luokitellut solmut/reunat

Esimerkki:

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

Muunna koko kaavio GraphFrameksi. Käyttää määritystietoja, kun ne ovat käytettävissä. muussa tapauksessa lukee järvien pöydistä.

Parametrit:

• column_mapping (Dict[str, str], optional): Mukautetun sarakkeen yhdistämismääritys

Palauttaa:

• GraphFrame: GraphFrame-objekti, jossa on kaikki kärkipisteet ja reunat

Esimerkki:

gf = graph.to_graphframe()

show

def show() -> None

Näytä kaavion tiedot. Edustajat monipuoliseen spec.show() näyttöön, kun määritys on liitetty; muussa tapauksessa tulostaa vain vähän tietoja.

show_schema

def show_schema() -> None

Näytä kaavion rakenne. Edustajat kohteeseen spec.show_schema() , kun määritys on liitetty; tulostaa viestin, joka ilmoittaa, että rakennetta ei muutoin ole käytettävissä.

publish (uusi versiossa v0.3.3)

def publish() -> Graph

Rekisteröi kaavio ohjelmointirajapinnalla, jolloin siitä voidaan tehdä kysely. Julkaise kaavioesiintymä kutsulla tämä myöhemmin Graph.prepare() (tai missä tahansa Graph , johon on liitetty määritys).

Palauttaa:

• Graph: Itse menetelmän ketjuttamiseen

Herättää:

• ValueError: Jos määritettä ei ole liitetty tai konteksti puuttuu
• RuntimeError: Jos julkaiseminen epäonnistuu

Esimerkki:

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

Koontiversion tila

Dataclass, joka sisältää metatietoja toiminnosta Graph.build() .

Kentät

Rakennepolut

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)

Esimerkki:

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

Solmun muodostajat

NodeBuilderInitial

Solmun muodostimen alkutila: vain käytettävissä olevat tietolähdemenetelmät.

Rakentaja

NodeBuilderInitial(alias: str, graph_builder: GraphSpecBuilder)

Huomautus: Luodaan yleensä -esiintymän kautta GraphSpecBuilder.add_node(), ei suoraan .

Menetelmiä

from_table

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

Määritä taulukko tietolähteeksi älykkäällä tietokannan tarkkuudella.

Parametrit:

• table_name (str): Taulukon nimi (pakollinen)
• database (str, valinnainen): Eksplisiittinen tietokannan nimi (on etusijalla kontekstin oletusarvoon nähden)

Palauttaa:

• NodeBuilderSourceSet: Muodostin lisämäärityksiä varten

Herättää:

• ValueError: Jos taulukkoa ei löydy tai löytyi useita ristiriitaisia taulukoita

Tietokannan ratkaisujärjestys:

1. Eksplisiittinen database parametri (korkein käsittelyjärjestys)
2. ExecutionContext.default_database
3. Hae kaikista tietokannoista (ristiriitojen tunnistukseen liittyvät)

Esimerkki:

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

from_dataframe

def from_dataframe(dataframe: DataFrame) -> NodeBuilderSourceSet

Määritä Spark DataFrame tietolähteeksi.

Parametrit:

• dataframe (DataFrame): Spark DataFrame

Palauttaa:

• NodeBuilderSourceSet: Muodostin lisämäärityksiä varten

Esimerkki:

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

NodeBuilderSourceSet

Solmun muodostin tietolähteen määrittämisen jälkeen: käytettävissä olevat määritysmenetelmät.

Rakentaja

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

Huomautus: Luotu sisäisesti NodeBuilderInitial-lähdemenetelmillä.

Menetelmiä

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

Käytä aikavälin suodatusta solmun tietolähteessä.

Parametrit:

• time_column (str): Aikaleimatietoja sisältävä sarakkeen nimi (pakollinen)
• start_time (str tai datetime, optional): Aloituspäivämäärä ('10/20/25', '2025-10-20', tai datetime-objekti)
• end_time (str tai datetime, optional): Päättymispäivä (samat muodot kuin start_time)
• lookback_hours (liukuluku, valinnainen): Taaksepäin katsomiseen tunnit tästä alkaen

Palauttaa:

• NodeBuilderSourceSet: Itse menetelmän ketjuttamiseen

Herättää:

• ValueError: Jos aikasaraketta ei löydy lähderakenteesta

Aika-alueen logiikka:

1. Jos start_time ja end_time annettu, käytä niitä suoraan
2. Jos vain lookback_hours annettu: end=now, start=now-lookback_hours
3. Jos mitään ei ole annettu: ei ajan suodatusta
4. Jos aloitus-/lopetus- JA-lookback_hours: aloitus ja lopetus ovat etusijalla

Esimerkki:

# 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

Aseta solmun otsikko (oletusarvo on alias, jos sitä ei kutsuta).

Parametrit:

• label (str): solmun otsikko

Palauttaa:

• NodeBuilderSourceSet: Itse menetelmän ketjuttamiseen

Herättää:

• ValueError: Jos selite on jo määritetty

Esimerkki:

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

with_columns

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

Määritä sarakkeet vaaditulla avaimella ja näyttömäärityksellä.

Parametrit:

• *columns (str): Sisällytettävät sarakkeiden nimet (vähintään yksi pakollinen)
• key (str): Avaimeksi merkittävän sarakkeen nimi (pakollinen, on oltava sarakkeissa)
• display (str): Sarakkeen nimi, joka merkitään näyttöarvoksi (pakollinen, on oltava sarakkeissa, voi olla sama kuin avain)

Palauttaa:

• NodeBuilderSourceSet: Itse menetelmän ketjuttamiseen

Herättää:

• ValueError: Jos vahvistus epäonnistuu (sarakkeiden kaksoiskappaleet, puuttuva avain/näyttö jne.)

Huomautuksia:

• Ominaisuudet luodaan automaattisesti saraketyypeistä

• Aikasuodatinsarake lisätään automaattisesti, jos se on määritetty

• Ominaisuustyypit johdetaan automaattisesti lähderakenteesta

• Näytä rajoitukset

Esimerkki:

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

Viimeistele tämä solmu ja ala rakentaa toista solmua.

Parametrit:

• alias (str): Uuden solmun tunnus

Palauttaa:

• NodeBuilderInitial: Uusi solmun muodostin

Esimerkki:

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

Viimeistele tämä solmu ja ala rakentaa reunaa.

Parametrit:

• alias (str): Reunan alias

Palauttaa:

• EdgeBuilderInitial: Uusi reunan muodostin

Esimerkki:

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

done

def done() -> GraphSpec

Viimeistele tämä solmu ja viimeistele kaaviomääritys.

Palauttaa:

• GraphSpec: Koko kaavion määritys

Esimerkki:

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

Reunan muodostajat

EdgeBuilderInitial

Reunan muodostimen alkutila: vain käytettävissä olevat tietolähdemenetelmät.

Rakentaja

EdgeBuilderInitial(alias: str, graph_builder: GraphSpecBuilder)

Huomautus: Luodaan yleensä -esiintymän kautta GraphSpecBuilder.add_edge(), ei suoraan .

Menetelmiä

from_table

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

Määritä taulukko tietolähteeksi älykkäällä tietokannan tarkkuudella.

Parametrit:

• table_name (str): Taulukon nimi (pakollinen)
• database (str, valinnainen): Eksplisiittinen tietokannan nimi

Palauttaa:

• EdgeBuilderSourceSet: Muodostin lisämäärityksiä varten

Herättää:

• ValueError: Jos taulukkoa ei löydy tai löytyi useita ristiriitaisia taulukoita

Esimerkki:

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

from_dataframe

def from_dataframe(dataframe: DataFrame) -> EdgeBuilderSourceSet

Määritä Spark DataFrame tietolähteeksi.

Parametrit:

• dataframe (DataFrame): Spark DataFrame

Palauttaa:

• EdgeBuilderSourceSet: Muodostin lisämäärityksiä varten

Esimerkki:

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

EdgeBuilderSourceSet

Edgen muodostin tietolähteen määrittämisen jälkeen: käytettävissä olevat määritysmenetelmät.

Rakentaja

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

Huomautus: Luotu sisäisesti EdgeBuilderInitial-lähdemenetelmillä.

Menetelmiä

with_label

def with_label(label: str) -> EdgeBuilderSourceSet

Määritä reunan suhteen tyyppi/selite (oletusarvo on alias, jos sitä ei kutsuta).

Parametrit:

• label (str): Reunan selite

Palauttaa:

• EdgeBuilderSourceSet: Itse menetelmän ketjuttamiseen

Herättää:

• ValueError: Jos selite on jo määritetty

Esimerkki:

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

edge_label

def edge_label(label: str) -> EdgeBuilderSourceSet

Määritä reunan suhteen tyyppi/selite (oletusarvo on alias, jos sitä ei kutsuta).

Parametrit:

• label (str): Reunan selite

Palauttaa:

• EdgeBuilderSourceSet: Itse menetelmän ketjuttamiseen

Herättää:

• ValueError: Jos selite on jo määritetty

Esimerkki:

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

source

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

Määritä lähdesolmu, jossa on tunnussarake ja -otsikko.

Parametrit:

• id_column (str): Lähdesolmun sisältävän sarakkeen nimi
• node_type (str): Lähdesolmun otsikko

Palauttaa:

• EdgeBuilderSourceSet: Itse menetelmän ketjuttamiseen

Herättää:

• ValueError: Jos lähde on jo määritetty

Esimerkki:

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

Määritä kohdesolmu tunnussarakkeella ja -selitteellä.

Parametrit:

• id_column (str): Kohdesolmun sisältävän sarakkeen nimi
• node_type (str): Kohdesolmun otsikko

Palauttaa:

• EdgeBuilderSourceSet: Itse menetelmän ketjuttamiseen

Herättää:

• ValueError: Jos tavoite on jo määritetty

Esimerkki:

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

Käytä aika-alueen suodatusta Edgen tietolähteessä.

Parametrit:

• time_column (str): Aikaleimatietoja sisältävä sarakkeen nimi (pakollinen)
• start_time (str tai datetime, optional): Aloituspäivämäärä
• end_time (str tai datetime, optional): lopetuspäivämäärä
• lookback_hours (liukuluku, valinnainen): Taaksepäin katsomiseen tunnit tästä alkaen

Palauttaa:

• EdgeBuilderSourceSet: Itse menetelmän ketjuttamiseen

Herättää:

• ValueError: Jos aikasaraketta ei löydy lähderakenteesta

Esimerkki:

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

Määritä sarakkeet vaaditulla avaimella ja näyttömäärityksellä.

Parametrit:

• *columns (str): Sisällytettävät sarakkeiden nimet (vähintään yksi pakollinen)
• key (str): Avaimeksi merkittävän sarakkeen nimi (pakollinen, on oltava sarakkeissa)
• display (str): Sarakkeen nimi, joka merkitään näyttöarvoksi (pakollinen, on oltava sarakkeissa)

Palauttaa:

• EdgeBuilderSourceSet: Itse menetelmän ketjuttamiseen

Herättää:

• ValueError: Jos vahvistus epäonnistuu

Esimerkki:

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

Viimeistele tämä reuna ja ala rakentaa solmua.

Parametrit:

• alias (str): Uuden solmun tunnus

Palauttaa:

• NodeBuilderInitial: Uusi solmun muodostin

add_edge

def add_edge(alias: str) -> EdgeBuilderInitial

Viimeistele tämä reuna ja ala rakentaa toista reunaa.

Parametrit:

• alias (str): Uuden reunan alias

Palauttaa:

• EdgeBuilderInitial: Uusi reunan muodostin

Esimerkki:

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

Viimeistele tämä reuna ja viimeistele kaavion määritys.

Palauttaa:

• GraphSpec: Koko kaavion määritys

Rakenneluokat

GraphDefinitionReference

Viittaus kaavion määritelmään, jossa on nimi ja versio.

Rakentaja

GraphDefinitionReference(
    fully_qualified_name: str,
    version: str
)

Parametrit:

• fully_qualified_name (str): Viitatun kaavion täydellinen nimi
• version (str): Viitatun kaavion versio

Herättää:

• ValueError: Jos fully_qualified_name tai versio on tyhjä

Menetelmiä

to_dict

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

Sarjoitetaan sanastoon.

Palauttaa:

• Dict[str, Any]: Sarjoitettu viittaus

Ominaisuus

Ominaisuusmääritelmä ja tyypin turvallinen liittymä.

Rakentaja

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
)

Parametrit:

• name (str): Ominaisuuden nimi
• property_type (PropertyType): Ominaisuuden tietotyyppi
• is_non_null (totuusarvo, oletus=Epätosi): Onko ominaisuus pakollinen
• description (str, default=""): Ominaisuuden kuvaus
• is_key (totuusarvo, oletus=Epätosi): Onko ominaisuus avain
• is_display_value (totuusarvo, oletusarvo=Epätosi): Onko ominaisuus näyttöarvo
• is_internal (totuusarvo, oletus=Epätosi): Onko ominaisuus sisäinen

Herättää:

• ValueError: Jos nimi on tyhjä tai vahvistus epäonnistuu

Luokan menetelmät

key

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

Luo avainominaisuus yleisillä asetuksilla (is_key=Tosi, is_display_value=Tosi).

display

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

Luo näyttöarvo-ominaisuus (is_display_value=Tosi).

Menetelmiä

describe

def describe(text: str) -> Property

Lisää kuvaus sujuvasti.

Parametrit:

• text (str): Kuvausteksti

Palauttaa:

• Property: Itse menetelmän ketjuttamiseen

to_dict

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

Sarjoita ominaisuus sanastoon @-etuliitteillä varustettujen huomautusavaimien avulla.

Palauttaa:

• Dict[str, Any]: Sarjoitettu ominaisuus

to_gql

def to_gql() -> str

Luo GQL-ominaisuusmääritys.

Palauttaa:

• str: GQL-merkkijonoesitys

EdgeNode

Reunamäärityksissä käytettävä solmuviittaus.

Rakentaja

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

Parametrit:

• alias (str, valinnainen): Solmun alias (aseta ensimmäiseksi selitteeksi, jos ei mitään tai tyhjä)
• labels (Luettelo[str]): solmun selitteet (vähintään yksi pakollinen)

Herättää:

• ValueError: Jos otsikkoluettelo on tyhjä
• TypeError: Jos otsikot eivät ole merkkijonoja

Automaattinen mutaatio:

• Jos alias on Ei mitään tai tyhjä, se on määritetty ensimmäiseksi selitteeksi

Menetelmiä

to_dict

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

Sarjoitetaan sanastoon.

Palauttaa:

• Dict[str, Any]: Sarjoitetun reunan solmuviittaus

Solmu

Solmun määritys tyypin kanssa turvallinen -käyttöliittymä.

Rakentaja

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
)

Parametrit:

• alias (str, default=""): Solmun alias (määritä automaattisesti ensimmäiseksi selitteeksi, jos se on tyhjä)
• labels (Luettelo[str]): solmun selitteet (vähintään yksi pakollinen)
• implies_labels (List[str], default=[]): Implisiittiset selitteet
• properties (List[Property], default=[]): Solmun ominaisuudet
• description (str, default=""): solmun kuvaus
• entity_group (str, default=""): Entiteettiryhmän nimi
• dynamic_labels (totuusarvo, oletus=Epätosi): Onko solmussa dynaamisia otsikoita
• abstract_edge_aliases (totuusarvo, oletus=epätosi): Käyttääkö solmu abstrakteja reuna-aliaksia

Herättää:

• ValueError: Jos vahvistus epäonnistuu (ei otsikoita, ei avainominaisuutta, ei näyttöominaisuutta jne.)

Automaattinen mutaatio:

• Jos alias on tyhjä, sen arvoksi määritetään ensimmäinen selite
• Jos entity_group on tyhjä, se on määritetty ensisijaiseksi selitteeksi

Menetelmiä

get_primary_label

def get_primary_label() -> Optional[str]

Hae ensisijainen (ensimmäinen) otsikko.

Palauttaa:

• str tai None: Ensisijainen selite tai Ei mitään, jos selitteitä ei ole

get_entity_group_name

def get_entity_group_name() -> str

Hae entiteettiryhmän nimi tai varatieto ensisijaiseen selitteeseen.

Palauttaa:

• str: Entiteettiryhmän nimi

get_primary_key_property_name

def get_primary_key_property_name() -> Optional[str]

Hanki perusavainominaisuuden nimi.

Palauttaa:

• str tai None: Perusavaimen ominaisuuden nimi

get_properties

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

Hanki ominaisuudet sanastona, jonka käyttö on helppoa.

Palauttaa:

• Dict[str, Property]: Nimen mukaan avaimiavat ominaisuudet

get_property

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

Hae tietty ominaisuus nimen mukaan.

Parametrit:

• name (str): Ominaisuuden nimi

Palauttaa:

• Property tai None: Ominaisuus, jos löytyy

add_property

def add_property(prop: Property) -> None

Lisää ominaisuus tähän solmuun.

Parametrit:

• prop (Ominaisuus): Lisättävä ominaisuus

Herättää:

• ValueError: Jos ominaisuuden nimi on jo olemassa

is_dynamically_labeled

def is_dynamically_labeled() -> bool

Tarkista, onko solmussa dynaamisia otsikoita.

Palauttaa:

• bool: Tosi, jos dynaamiset selitteet ovat käytössä

is_abstract_edge_node_aliases

def is_abstract_edge_node_aliases() -> bool

Tarkista, käyttääkö solmu abstraktia reunasolmun aliaksia.

Palauttaa:

• bool: Tosi, jos abstraktit reuna-aliakset ovat käytössä

describe

def describe(text: str) -> Node

Lisää kuvaus sujuvasti.

Parametrit:

• text (str): Kuvausteksti

Palauttaa:

• Node: Itse menetelmän ketjuttamiseen

to_dict

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

Sarjoita solmu sanastoon.

Palauttaa:

• Dict[str, Any]: Sarjoitettu solmu

to_gql

def to_gql() -> str

Luo GQL-solmun määritys.

Palauttaa:

• str: GQL-merkkijonoesitys

Herättää:

• ValueError: Jos solmussa ei ole GQL:n pakollisia kenttiä

Luokan menetelmät

create

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

Luo solmu, joka sisältää kaikki pakolliset kentät.

Parametrit:

• alias (str): solmun tunnus
• labels (Luettelo[str]): solmun selitteet
• properties (Luettelo[Ominaisuus]): solmun ominaisuudet
• description (str, default=""): solmun kuvaus
• entity_group (str, default=""): Entiteettiryhmän nimi

Palauttaa:

• Node: Uusi solmuesiintymä

Reuna

Edge-määritys ja tyypin turvallinen käyttöliittymä.

Rakentaja

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
)

Parametrit:

• relationship_type (str): Reunan suhdetyyppi (esimerkiksi "SEURAA", "OWNS")
• source_node_label (str): Lähdesolmun otsikko
• target_node_label (str): Kohdesolmun otsikko
• direction (EdgeDirection, default=DIRECTED_RIGHT): Reunan suunta
• properties (Luettelo[Ominaisuus], oletus=[]): Edgen ominaisuudet
• description (str, default=""): Edgen kuvaus
• entity_group (str, default=""): Entiteettiryhmän nimi
• dynamic_type (totuusarvo, oletus=Epätosi): Onko Edgessä dynaaminen tyyppi

Herättää:

• ValueError: Jos vahvistus epäonnistuu

Automaattinen mutaatio:

• labels luettelo täytetään automaattisesti [relationship_type]
• Jos entity_group on tyhjä, sen arvoksi määritetään relationship_type

Ominaisuudet

edge_type

def edge_type() -> str

relationship_type yhteensopivuuden aiempi tunnus.

Palauttaa:

• str: Suhdetyyppi

Menetelmiä

get_entity_group_name

def get_entity_group_name() -> str

Hae entiteettiryhmän nimi tai varayhteys suhdetyyppiin.

Palauttaa:

• str: Entiteettiryhmän nimi

is_dynamic_type

def is_dynamic_type() -> bool

Tarkista, onko Edgessä dynaaminen tyyppi.

Palauttaa:

• bool: Tosi, jos dynaaminen tyyppi

add_property

def add_property(edge_property: Property) -> None

Lisää ominaisuus tähän reunaan.

Parametrit:

• edge_property (Ominaisuus): Lisättävä ominaisuus

describe

def describe(text: str) -> Edge

Lisää kuvaus sujuvasti.

Parametrit:

• text (str): Kuvausteksti

Palauttaa:

• Edge: Itse menetelmän ketjuttamiseen

to_dict

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

Sarjoittaa reuna sanastoon.

Palauttaa:

• Dict[str, Any]: Sarjoitettu reuna

to_gql

def to_gql() -> str

Luo GQL-reunamääritys.

Palauttaa:

• str: GQL-merkkijonoesitys

Luokan menetelmät

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

Luo reuna, joka sisältää kaikki pakolliset kentät.

Parametrit:

• relationship_type (str): Edge-suhdetyyppi
• source_node_label (str): Lähdesolmun otsikko
• target_node_label (str): Kohdesolmun otsikko
• properties (List[Property], optional): Edge-ominaisuudet
• description (str, default=""): Edgen kuvaus
• entity_group (str, default=""): Entiteettiryhmän nimi

Palauttaa:

• Edge: Uusi Edge-esiintymä

GraphSchema

Graph-rakenteen määritys ja tyyppiturvallinen liittymä.

Rakentaja

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

Parametrit:

• name (str): Graph-rakenteen nimi
• nodes (List[Node], default=[]): Solmumääritykset
• edges (List[Edge], default=[]): Edge-määritykset
• base_graphs (List[GraphSchema], default=[]): Peruskaaviorakenteet
• description (str, default=""): Rakenteen kuvaus
• version (str, default="1.0"): Rakenneversio
• fully_qualified_name (str, default=""): Täydellinen nimi
• namespace (str, default=""): Nimitila

Herättää:

• ValueError: Jos vahvistus epäonnistuu (aliasten kaksoiskappaleet, reunat viittaavat solmuihin, joita ei ole)

Menetelmiä

get_fully_qualified_name

def get_fully_qualified_name() -> str

Hae täydellinen nimi.

Palauttaa:

• str: Täydellinen nimi

get_namespace

def get_namespace() -> str

Hae nimitila täydellisestä nimestä tai palauta oletus.

Palauttaa:

• str:Namespace

get_version

def get_version() -> str

Hanki versio.

Palauttaa:

• str: Versiomerkkijono

get_node

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

Hae solmu selitteen tai aliaksen mukaan.

Parametrit:

• label_or_alias (str): solmun otsikko tai tunnus

Palauttaa:

• Node tai None: Solmu, jos löytyy

get_edge

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

Hae reuna nimen tai tyypin mukaan.

Parametrit:

• name (str): Edge-suhdetyyppi

Palauttaa:

• Edge tai None: Edge, jos löytyi

add_node

def add_node(node: Node) -> None

Lisää solmu tähän kaavioon.

Parametrit:

• node (solmu): lisättävä solmu

Herättää:

• ValueError: Jos solmun alias on kaksoiskappale

add_edge

def add_edge(edge: Edge) -> None

Lisää reuna tähän kaavioon.

Parametrit:

• edge (Reuna): Lisättävä reuna

Herättää:

• ValueError: Jos reunan tyyppi on kaksoiskappale

include_graph

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

Lisää kaavion sisällytys (sujuva ohjelmointirajapinta).

Parametrit:

• fully_qualified_name (str): Sisällytettävän kaavion täydellinen nimi
• version (str): Sisällytettävä kaavion versio

Palauttaa:

• GraphSchema: Itse menetelmän ketjuttamiseen

get_included_graph_references

def get_included_graph_references() -> List[GraphDefinitionReference]

Hae luettelo sisällytetyistä kaavioviittauksista.

Palauttaa:

• List[GraphDefinitionReference]: Luettelo kaavion määritysviittauksista

describe

def describe(text: str) -> GraphSchema

Lisää kuvaus sujuvasti.

Parametrit:

• text (str): Kuvausteksti

Palauttaa:

• GraphSchema: Itse menetelmän ketjuttamiseen

to_dict

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

Sarjoita rakenne sanastoon.

Palauttaa:

• Dict[str, Any]: Sarjoitettu rakenne

to_json

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

Luo JSON-esitys.

Parametrit:

• indent (kokonaisarvo, oletus=2): JSON-sisennystaso

Palauttaa:

• str: JSON-merkkijono

to_gql

def to_gql() -> str

Luo GQL-rakennemääritys.

Palauttaa:

• str: GQL-merkkijonoesitys

Luokan menetelmät

create

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

Luo kaavion rakenne, joka sisältää kaikki pakolliset kentät.

Parametrit:

• name (str): Graph-rakenteen nimi
• nodes (List[Node], valinnainen): solmumääritykset
• edges (List[Edge], valinnainen): Edge-määritykset
• description (str, default=""): Rakenteen kuvaus
• version (str, default="1.0"): Rakenneversio

Palauttaa:

• GraphSchema: Uusi kaavion rakenteen esiintymä

Kyselyn syöteluokat

Tietoluokat, jotka edustavat esimääritettyjen kaaviokyselyiden syöteparametreja.

QueryInputBase

Kaikkien kyselyn syöteparametrien perusluokka.

Menetelmiä

to_json_payload

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

Muunna syöteparametrit sanastoksi ohjelmointirajapinnan lähettämistä varten.

Palauttaa:

• Dict[str, Any]: Syöteparametrien sanastoesitys

validate

def validate() -> None

Vahvista syöteparametrit.

Herättää:

• ValueError: Jos syöteparametrit ovat virheelliset

ReachabilityQueryInput

Lähde- ja kohdesolmujen välisen tavoitettavuuskyselyn syöteparametrit. Periytyvät QueryInputBasekohteesta ReachabilityQueryInputBase .

Kentät

Validation:

• source_property_value on pakollinen
• target_property_value on pakollinen

Esimerkki:

# 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

Tietyn lähdesolmun k-hop-kyselyn syöteparametrit. Perii kohteesta ReachabilityQueryInputBase.

Perii kaikki kentät kohteesta ReachabilityQueryInput.

Validation:

• Vähintään yksi tai source_property_valuetarget_property_value on annettava

Esimerkki:

# 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

Syöteparametrit räjähdyssädekyselylle lähteestä kohdesolmuihin. Perii kohteesta ReachabilityQueryInputBase.

Perii kaikki kentät kohteesta ReachabilityQueryInputja sisältää seuraavat pakolliset kentät:

Validation:

• source_property_value on pakollinen
• target_property_value on pakollinen

Esimerkki:

# 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

Keskisyysanalyysikyselyn syöteparametrit. Perii kohteesta QueryInputBase.

CentralityType-luettelointi

Kentät

Esimerkki:

# 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

Luokitellun analyysikyselyn syöteparametrit. Perii kohteesta QueryInputBase.

Kentät

Esimerkki:

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

Kyselyn tulokset

QueryResult

Tulos kaaviokyselystä, jossa DataFrame-käyttöoikeus on laiska.

Rakentaja

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

Parametrit:

• raw_response (Dict[str, Any]): API-raakavastaussanasto
• graph (Kaavio): Viittaus pääkaavioon

Huomautus: Yleensä luoja: , ei Graph.query()suoraan luotu.

Menetelmiä

to_dataframe

def to_dataframe() -> DataFrame

Muuntaa kyselyn tuloksen Spark DataFrame -muotoon.

Palauttaa:

• DataFrame: Kyselyn tulos Spark DataFrame -muodossa

Herättää:

• ValueError: Jos muunnos epäonnistuu

Esimerkki:

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

get_raw_data

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

Hae RawData-osa vastauksesta.

Palauttaa:

• Dict[str, Any]: Sanasto, jossa on raakametatiedot, tai tyhjä sanelu, jos sitä ei ole

Esimerkki:

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

show

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

Näytä kyselyn tulos eri muodoissa.

Parametrit:

• format (str, default="visual"): Tulostemuoto
  • "table": Täydet DataFrame-taulukot (kaikki sarakkeet)
  • "visual": Vuorovaikutteinen kaaviovisualisointi VSC-laajennuksella
  • "all": Näytä kaikki muodot

Herättää:

• ValueError: Jos muoto ei ole yksi tuetuista arvoista

Esimerkki:

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

Täydellinen esimerkki (suositus – 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()

Suunnittelumalleja koskevat muistiinpanot

Fluent-ohjelmointirajapinta

Kaikki koontiversiot tukevat menetelmäketjua luettavissa ja deklaratiivisissa kaaviomäärityksissä:

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

Union-rakenteet

Useita reunoja, joilla on sama alias, yhdistetään automaattisesti yhdistettyjen ominaisuuksien kanssa:

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

Automaattinen määritys

Monilla kentillä on järkevät oletusarvot:

• Solmujen/reunan otsikoiden oletusarvo on niiden aliakset
• Ominaisuudet määritetään automaattisesti lähderakenteista
• Entiteettiryhmät käyttävät oletusarvoisesti ensisijaisia otsikoita/suhdetyyppejä

Laiska arviointi

DataFrames ja resurssit ladataan laiskusti ja tallennetaan välimuistiin:

• graph_spec.nodes ja graph_spec.edges ladataan ensimmäisellä käyttöoudella
• Kyselytulokset luovat DataFrames-kehykset vain pyydettäessä

Aiheeseen liittyvä sisältö

• Mukautettujen kaavioiden yleiskatsaus
• Mukautettujen kaavioiden luominen