Skema grafik properti

neptune.graph.pg_schema()Prosedur ini memberikan gambaran menyeluruh tentang struktur grafik properti Anda. Ini mengembalikan semua label node, label tepi, properti dengan tipe datanya, dan label tiga kali lipat ({~from, ~type, ~to}pola yang menggambarkan bagaimana tipe node terhubung melalui tipe tepi).

Prosedur ini saat ini hanya tersedia melalui titik akhir OpenCypher dan menemukan skema untuk semua data grafik properti.

Gunakan prosedur ini untuk tugas-tugas seperti:

• Pembuatan kueri AI dan LLM - Berikan LLM struktur grafik yang mereka butuhkan untuk menghasilkan kueri Cypher yang valid dari bahasa alami (Text-to-Cypher, aplikasi GraphRag).

• Visualisasi dan eksplorasi grafik — Alat seperti Graph Explorer menggunakan informasi skema untuk membuat representasi visual interaktif dari data grafik tanpa memindai seluruh database.

• Penemuan skema aplikasi — Aplikasi yang perlu memahami struktur grafik saat startup, seperti generator skema GraphQL atau alat validasi data.

Perbandingan dengan Neptune Analytics

Di Neptunus Analytics neptune.graph.pg_schema(), sinkron. Ini menghitung skema pada setiap panggilan.

Di Database Neptunus, Anda secara eksplisit memicu perhitungan skema asinkron dengan memanggil, yang segera kembali. neptune.graph.pg_schema.compute() Perhitungan berjalan di latar belakang saat Anda melakukan polling untuk penyelesaian menggunakan. neptune.graph.pg_schema() Setelah dihitung, Neptunus mempertahankan skema dan mengembalikannya secara instan pada pembacaan berikutnya tanpa perhitungan ulang. Hasil sebagian juga tersedia saat perhitungan masih berlangsung. Anda juga dapat menghentikan perhitungan yang sedang berjalan dan melanjutkannya nanti.

Perbandingan dengan API Ringkasan Grafik

API Ringkasan Grafik tidak menyediakan tiga label atau tipe data properti. Prosedur skema grafik properti mengisi celah ini. Tiga label menunjukkan pola hubungan tertentu dalam grafik Anda. Misalnya, Person menghubungkan ke worksAt tepi Company via. Informasi ini sangat penting bagi LLM untuk menghasilkan kueri yang benar secara semantik.

Prasyarat

Versi mesin

Prosedur skema grafik properti memerlukan mesin Neptunus versi 1.4.8.0 atau yang lebih baru.

Izin IAM

Tindakan IAM berikut diperlukan untuk setiap operasi skema:

• CALL neptune.graph.pg_schema()— membutuhkanneptune-db:ReadDataViaQuery.

• CALL neptune.graph.pg_schema.compute()— membutuhkan neptune-db:ReadDataViaQuery danneptune-db:WriteDataViaQuery.

• CALL neptune.graph.pg_schema.stop()— membutuhkan neptune-db:ReadDataViaQuery danneptune-db:WriteDataViaQuery.

stop()Operasi compute() dan memerlukan izin menulis karena mereka memodifikasi status internal yang digunakan untuk cache dan mempertahankan skema.

contoh Contoh kebijakan IAM

Kebijakan berikut memberikan izin minimum yang diperlukan untuk semua operasi skema:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "neptune-db:ReadDataViaQuery",
      "neptune-db:WriteDataViaQuery"
    ],
    "Resource": "arn:aws:neptune-db:us-east-1:123456789012:cluster-resource-id/*"
  }]
}

Untuk memberikan akses hanya-baca ke skema (tanpa kemampuan untuk memicu komputasi), gunakan saja. neptune-db:ReadDataViaQuery

Contoh penulis dan pembaca

Anda dapat memicu perhitungan skema hanya pada instance penulis. Contoh replika baca dapat membaca skema (yang direplikasi dari penulis) tetapi tidak dapat dijalankan atau. compute() stop()

Referensi API

Baca skema

Mengambil skema saat ini dan status komputasi.

Sintaksis:

AWS CLI

aws neptunedata execute-open-cypher-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "CALL neptune.graph.pg_schema()"

SDK

import boto3
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

response = client.execute_open_cypher_query(
    openCypherQuery='CALL neptune.graph.pg_schema()'
)

print(response)

awscurl

awscurl -X POST https://your-neptune-endpoint:port/openCypher \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --region us-east-1 --service neptune-db \
  -d 'query=CALL neptune.graph.pg_schema()'

Perilaku: Segera kembali dengan skema dan status saat ini. Selalu tidak memblokir. Jika tidak ada skema yang dihitung, mengembalikan state: "NotStarted" dengan bidang skema kosong. Jika perhitungan sedang berlangsung, mengembalikan sebagian hasil dengan status:. "InProgress"

Format respons:

Respons berisi objek skema dengan bidang-bidang berikut:

Objek status:

• state(String) - Status siklus hidup saat ini:NotStarted,,,InProgress, Completed Stopped Failed

• concurrency(String) - Jumlah utas yang digunakan untuk perhitungan. 0 berarti auto (ditentukan berdasarkan perangkat keras). Rentang: 1 (terendah) hingga 16 (tertinggi).

• lastComputedTimestamp(String) — stempel waktu ISO-8601 UTC dari perhitungan terakhir yang berhasil (mis.,) 2026-05-29T08:00:00Z

• progressPercentage(String) - Kemajuan komputasi: 0 saat tidak dimulai, 0—99 selama komputasi, 100 saat selesai

• errorMessage(String) - Hadir hanya ketika permintaan ditolak atau perhitungan gagal. Menjelaskan alasannya.

Objek skema:

• nodeLabels— Array dari semua label node unik dalam grafik

• edgeLabels— Array semua label tepi unik dalam grafik

• nodeLabelDetails— Untuk setiap label node: properti dan tipe datanya

• edgeLabelDetails— Untuk setiap label tepi: properti dan tipe datanya

• labelTriples— Array pola hubungan: {~from, ~type, ~to} menggambarkan tipe simpul mana yang terhubung melalui tipe tepi mana

Tipe data yang didukung: StringInt,Long,,Double,Bool, Date

Jika properti memiliki beberapa tipe data di seluruh node yang berbeda (misalnya, beberapa node menyimpan age sebagai Int dan lainnya sebagaiString), semua tipe yang diamati tercantum dalam datatypes array.

Skema komputasi

Memicu perhitungan skema latar belakang.

Sintaksis:

AWS CLI

aws neptunedata execute-open-cypher-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "CALL neptune.graph.pg_schema.compute()"

Dengan parameter konkurensi opsional:

aws neptunedata execute-open-cypher-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "CALL neptune.graph.pg_schema.compute({concurrency: 2})"

SDK

import boto3
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

response = client.execute_open_cypher_query(
    openCypherQuery='CALL neptune.graph.pg_schema.compute()'
)

print(response)

awscurl

awscurl -X POST https://your-neptune-endpoint:port/openCypher \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --region us-east-1 --service neptune-db \
  -d 'query=CALL neptune.graph.pg_schema.compute()'

Dengan parameter konkurensi opsional:

awscurl -X POST https://your-neptune-endpoint:port/openCypher \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --region us-east-1 --service neptune-db \
  -d 'query=CALL neptune.graph.pg_schema.compute({concurrency: 2})'

Tindakan IAM diperlukan: neptune-db:ReadDataViaQuery dan neptune-db:WriteDataViaQuery

Parameter:

• concurrency(Integer, opsional) - Jumlah utas untuk perhitungan latar belakang. 0 (default) = ditentukan secara otomatis berdasarkan perangkat keras. Rentang: 1 (terendah) hingga 16 (tertinggi). Gunakan nilai yang lebih rendah pada instance yang lebih kecil untuk mengurangi dampak sumber daya.

Perilaku:

• Kembali segera dengan status saat ini. Perhitungan berjalan secara asinkron di latar belakang.

• Jika dipanggil ketika statusnyaStopped, perhitungan dilanjutkan dari tempat tinggalkannya.

• Jika dipanggil ketika state isCompleted, mulai perhitungan ulang baru. Skema sebelumnya terus menyajikan pembacaan sampai perhitungan baru selesai.

• Jika dipanggil ketika perhitungan sudah, InProgress Neptunus menolak permintaan dengan pesan kesalahan.

• Jika dipanggil selama pemuatan massal aktif, Neptunus menolak permintaan dengan pesan kesalahan.

Respon: Mengembalikan objek status yang menunjukkan status: "InProgress" dengan concurrency dan progressPercentage bidang.

Hentikan perhitungan skema

Menghentikan perhitungan latar belakang yang sedang berjalan.

Sintaksis:

AWS CLI

aws neptunedata execute-open-cypher-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "CALL neptune.graph.pg_schema.stop()"

SDK

import boto3
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

response = client.execute_open_cypher_query(
    openCypherQuery='CALL neptune.graph.pg_schema.stop()'
)

print(response)

awscurl

awscurl -X POST https://your-neptune-endpoint:port/openCypher \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --region us-east-1 --service neptune-db \
  -d 'query=CALL neptune.graph.pg_schema.stop()'

Tindakan IAM diperlukan: neptune-db:ReadDataViaQuery dan neptune-db:WriteDataViaQuery

Perilaku:

• Menghentikan perhitungan yang sedang berjalan. Kemajuan disimpan sehingga dapat melanjutkan dari tempat yang ditinggalkannya saat Anda menelepon compute() lagi.

• Perhitungan yang berhenti tidak secara otomatis dilanjutkan saat mesin restart. Anda harus menelepon secara eksplisit. compute()

Respon: Mengembalikan objek status yang menunjukkan status: "Stopped" dengan arusprogressPercentage.

Menggunakan YIELD dengan hasil skema

Anda dapat menggunakan YIELD untuk mengekstrak bidang skema dan menggabungkannya dengan kueri lain. Contoh berikut mengambil semua label node dan menghitung jumlah node untuk setiap label. collSort()Fungsi mengurutkan daftar menurut abjad:

CALL neptune.graph.pg_schema()
  YIELD schema
  WITH schema.nodeLabels as nl
  UNWIND collSort(nl) as label
  MATCH (n)
  WHERE label in labels(n)
  RETURN label, COUNT(n) as count

Contoh output:

{
  "results": [{
      "label": "airport",
      "count": 3503
    }, {
      "label": "continent",
      "count": 7
    }, {
      "label": "country",
      "count": 237
    }, {
      "label": "version",
      "count": 1
    }]
}

Siklus hidup perhitungan skema

Operasi asinkron

Komputasi skema adalah operasi asinkron. Saat Anda meneleponneptune.graph.pg_schema.compute(), ia segera kembali dengan status saat ini. Perhitungan berjalan di latar belakang. Anda melakukan polling untuk kemajuan dan penyelesaian dengan meneleponneptune.graph.pg_schema(), yang mengembalikan status saat ini danprogressPercentage.

Status

Komputasi skema bergerak melalui status berikut:

• NotStarted— Belum ada skema yang dihitung. pg_schema()mengembalikan skema kosong.

• InProgress— Perhitungan latar belakang sedang berjalan. pg_schema()mengembalikan sebagian hasil (penyatuan skema lengkap terakhir dan penemuan dari perhitungan saat ini).

• Completed— Perhitungan selesai dengan sukses. Skema lengkap tersedia.

• Stopped— Perhitungan dihentikan, baik dengan menelepon stop() atau karena restart mesin memotongnya. Hasil sebagian tersedia. Kemajuan disimpan sehingga perhitungan dapat dilanjutkan dari tempat yang ditinggalkan saat Anda menelepon. compute()

• Failed— Perhitungan mengalami kesalahan. Skema terakhir yang berhasil dihitung (jika ada) tetap tersedia.

Kegigihan dan memulai kembali perilaku

Skema yang dihitung dipertahankan dan bertahan dari restart mesin. Perilaku restart tergantung pada status pada saat restart:

• InProgress— Jika mesin restart selama komputasi, perhitungan beralih ke. Stopped Panggilan compute() untuk melanjutkan dari tempat yang ditinggalkannya. Kemajuan dipertahankan dan perhitungan berlanjut dari pos pemeriksaan terakhirnya.

• Stopped— Perhitungan tidak secara otomatis dilanjutkan. Anda harus menelepon compute() untuk melanjutkan dari tempat yang ditinggalkannya.

• Completed— Skema dimuat dan tersedia segera.

Hasil sebagian

Sementara perhitungan sedang berlangsung, pg_schema() mengembalikan sebagian hasil. Ini termasuk skema yang telah diselesaikan sebelumnya yang digabungkan dengan label, properti, dan tiga kali lipat yang ditemukan sejauh ini dalam perhitungan saat ini. Ini berarti Anda tidak perlu menunggu perhitungan lengkap selesai sebelum mengambil informasi skema yang berguna.

Replika baca

Contoh replika baca dapat membaca skema menggunakan. CALL neptune.graph.pg_schema() Neptunus mereplikasi skema dari contoh penulis dan membuatnya tersedia di replika segera saat elemen skema ditemukan pada penulis.

Baca replika tidak dapat dijalankan compute() ataustop(). Panggilan ini mengembalikan kesalahan:

• compute() – "Schema cannot be computed on read replica"

• stop() – "Schema compute cannot be stopped on read replica"

Praktik terbaik

• Komputasi ulang setelah mutasi — Skema tidak diperbarui secara otomatis saat data berubah. Hitung ulang skema setelah beban massal atau mutasi data yang signifikan. Gunakan lastComputedTimestamp bidang untuk menentukan apakah skema sudah usang relatif terhadap perubahan terbaru dalam grafik Anda.

• Concurrency — Nilai konkurensi default (0) secara otomatis menyesuaikan dengan perangkat keras instans Anda. Untuk sebagian besar beban kerja, ini adalah pengaturan yang disarankan. Jika perhitungan latar belakang memengaruhi beban kerja kueri Anda, tentukan nilai yang lebih rendah (misalnya, 1 atau 2) untuk mengurangi penggunaan sumber daya.

• Hentikan dan lanjutkan — Jika perhitungan latar belakang memengaruhi beban kerja kueri Anda, hentikan stop() dan lanjutkan nanti selama periode lalu lintas yang lebih rendah dengan menelepon lagi. compute() Perhitungan berlanjut dari tempat ia tinggalkan.

• Tangani restart dengan anggun — Jika mesin dinyalakan kembali saat perhitungan skema sedang berlangsung, perhitungan akan beralih ke. Stopped Panggilan compute() untuk melanjutkan dari tempat yang ditinggalkannya. Kemajuan dipertahankan.

• Database besar — Untuk database dengan volume penyimpanan besar (beberapa TB), perhitungan skema penuh mungkin memakan waktu lama. Anda dapat memulai komputasi, biarkan berjalan hingga 10-20% kemajuan, lalu berhenti. Hasil sebagian yang dikumpulkan selama jendela ini memberikan sampel skema yang berguna dengan banyak label, properti, dan tiga kali lipat yang sudah ditemukan. Baca skema sebagian dengan pg_schema() saat perhitungan sedang berlangsung atau setelah berhenti. Lanjutkan nanti saat beban kerja Anda memungkinkan.

Batasan

• Penghapusan memerlukan perhitungan ulang — Label, properti, dan tiga kali lipat yang dihapus hanya dihapus dari skema setelah perhitungan ulang penuh berikutnya. Sampai saat itu, elemen yang dihapus mungkin masih muncul dalam hasil skema.

• OpenCypher hanya - Anda dapat memanggil prosedur ini hanya melalui titik akhir kueri OpenCypher.

• Tidak dapat menghitung selama beban massal — Neptunus menolak perhitungan skema saat operasi beban massal aktif. Pemicu komputasi setelah beban massal selesai.

Output sampel

Contoh berikut menunjukkan output skema untuk dataset rute udara:

awscurl -X POST https://your-neptune-endpoint:port/openCypher \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --region us-east-1 --service neptune-db \
  -d 'query=CALL neptune.graph.pg_schema()'

{
  "results": [{
      "schema": {
        "edgeLabelDetails": {
          "route": {
            "properties": {
              "dist": ["Int"]
            }
          },
          "contains": {
            "properties": {}
          }
        },
        "edgeLabels": ["route", "contains"],
        "status": {
          "concurrency": "16",
          "lastComputedTimestamp": "2026-06-04T23:58:17Z",
          "state": "Completed",
          "progressPercentage": "100"
        },
        "nodeLabels": ["version", "continent", "airport", "country"],
        "labelTriples": [{
            "~type": "route",
            "~from": "airport",
            "~to": "airport"
          }, {
            "~type": "contains",
            "~from": "country",
            "~to": "airport"
          }, {
            "~type": "contains",
            "~from": "continent",
            "~to": "airport"
          }],
        "nodeLabelDetails": {
          "continent": {
            "properties": {
              "type": ["String"],
              "code": ["String"],
              "desc": ["String"]
            }
          },
          "airport": {
            "properties": {
              "type": ["String"],
              "city": ["String"],
              "icao": ["String"],
              "code": ["String"],
              "country": ["String"],
              "lat": ["Double"],
              "longest": ["Int"],
              "runways": ["Int"],
              "desc": ["String"],
              "lon": ["Double"],
              "region": ["String"],
              "elev": ["Int"]
            }
          },
          "country": {
            "properties": {
              "type": ["String"],
              "code": ["String"],
              "desc": ["String"]
            }
          },
          "version": {
            "properties": {
              "date": ["String"],
              "desc": ["String"],
              "author": ["String"],
              "type": ["String"],
              "code": ["String"]
            }
          }
        }
      }
    }]
}