คู่มือภาษา GQL สําหรับกราฟใน Microsoft Fabric

GQL (Graph Query Language) เป็นภาษาคิวรีที่ได้มาตรฐาน ISO สําหรับฐานข้อมูลกราฟ ใช้ GQL เพื่อคิวรี วิเคราะห์ และทํางานกับข้อมูลกราฟอย่างมีประสิทธิภาพด้วยกราฟใน Microsoft Fabric

กลุ่มการทํางาน ISO เดียวกันที่กําหนดมาตรฐาน SQL พัฒนา GQL ด้วยเหตุนี้ GQL จึงแชร์แนวคิดมากมายกับ SQL รวมถึงนิพจน์ เพรดิเคต และชนิดข้อมูล ถ้าคุณมีประสบการณ์ SQL คุณสามารถนําความรู้นั้นไปใช้กับ GQL ได้

บทความนี้เป็นคู่มือครบวงจรสําหรับ GQL ในกราฟ มันอธิบายว่าภาษานี้เชื่อมโยงกันอย่างไร และลิงก์ไปยังการอ้างอิงเฉพาะเพื่อรายละเอียดไวยากรณ์และชนิดข้อมูลที่ครบถ้วน ครอบคลุมถึง:

  • แนวคิดหลัก: กราฟโครงสร้างข้อมูล รูปแบบ และพื้นฐานของคิวรี
  • ประโยคสําคัญ: MATCH, FILTER, LET, WHEN, ORDER BY, , LIMIT, และ RETURN
  • ชนิดข้อมูลและนิพจน์: ชนิดค่า ตัวดําเนินการ และฟังก์ชันที่มีอยู่ภายใน
  • เทคนิคขั้นสูง: องค์ประกอบแบบหลายคําสั่ง การกําหนดขอบเขตตัวแปร และกลยุทธ์การรวม

Note

มาตรฐานสากลอย่างเป็นทางการสําหรับ GQL คือเทคโนโลยีสารสนเทศ ISO/IEC 39075 - Database Languages - GQL

หากคุณกําลังมองหาคําแนะนําที่เน้นงานแทนการสอนภาษา ดูคู่มือวิธีทํา:

ใช้บทความอ้างอิงเฉพาะเมื่อคุณต้องการรายละเอียดครบถ้วน:

ข้อมูลที่จําเป็น บทความถาวร
ไวยากรณ์โดยสรุป การอ้างอิงด่วนของ GQL
ไวยากรณ์ของโหนด, ขอบ, เส้นทาง และรูปแบบ รูปแบบกราฟ GQL
ตัวดําเนินการ พรีดิเคต และฟังก์ชัน นิพจน์ GQL เพรดิเคต และฟังก์ชัน
ไวยากรณ์ตามตัวอักษร พฤติกรรมค่า และการแปลงประเภทข้อมูล ค่า GQL และชนิดของค่า
คําจํากัดความและข้อจํากัดของประเภทกราฟ ชนิดกราฟ GQL
การครอบคลุมฟีเจอร์ ISO GQL ในปัจจุบัน ความสอดคล้องมาตรฐาน GQL
ข้อจํากัดและข้อจํากัดเฉพาะของ Fabric ในปัจจุบัน ข้อจํากัดในปัจจุบัน

ข้อกําหนดเบื้องต้น

ก่อนที่คุณจะเริ่มต้น ตรวจสอบให้แน่ใจว่าคุณคุ้นเคยกับแนวคิดเหล่านี้:

  • ความเข้าใจเกี่ยวกับฐานข้อมูล Basic - ประสบการณ์การใช้งานกับระบบฐานข้อมูลใด ๆ เช่น เชิงสัมพันธ์ (SQL), NoSQL หรือกราฟจะมีประโยชน์
  • แนวคิดของกราฟ - การทําความเข้าใจเกี่ยวกับโหนด ขอบ และความสัมพันธ์ในข้อมูลที่เชื่อมต่อ
  • พื้นฐานของคิวรี - ความรู้เกี่ยวกับแนวคิดคิวรีพื้นฐาน เช่น การกรอง การเรียงลําดับ และการรวม

พื้นหลังที่แนะนํา:

  • ประสบการณ์การใช้งานภาษา SQL หรือ openCypher ทําให้การเรียนรู้ไวยากรณ์ GQL ง่ายขึ้น (เป็นรากของ GQL)
  • ความคุ้นเคยกับการสร้างแบบจําลองข้อมูลช่วยด้วยการออกแบบ Schema ของกราฟ
  • ทําความเข้าใจเกี่ยวกับกรณีการใช้งานเฉพาะของคุณสําหรับข้อมูลกราฟ

สิ่งที่คุณต้องการ:

  • เข้าถึงพื้นที่ทํางานกราฟด้วยความสามารถของคิวรี
  • ตัวอย่างข้อมูลหรือความยินดีที่จะทํางานกับตัวอย่างเครือข่ายสังคมออนไลน์ของเรา
  • ตัวแก้ไขข้อความพื้นฐานสําหรับการเขียนคิวรี

เคล็ดลับ

ถ้าคุณไม่คุ้นเคยกับฐานข้อมูลกราฟ เริ่มต้นด้วย ภาพรวมแบบจําลองข้อมูลกราฟ ก่อนดําเนินการต่อตามคู่มือนี้

สิ่งที่ทําให้ GQL พิเศษ

GQL ถูกออกแบบมาโดยเฉพาะสําหรับข้อมูลกราฟ ดังนั้นไวยากรณ์ของมันจึงแสดงโดยตรงว่าเอนทิตีเชื่อมต่อกันอย่างไร ในขณะที่ SQL มักแสดงความสัมพันธ์ผ่านการเชื่อมระหว่างตาราง GQL ใช้รูปแบบกราฟที่คล้ายกับแผนภาพของข้อมูล

ตัวอย่างเช่น คําค้นต่อไปนี้จะค้นหาคู่ของคนที่รู้จักกันและเกิดก่อนปี 1999:

MATCH (person:Person)-[:knows]-(friend:Person)
WHERE person.birthday < 19990101
  AND friend.birthday < 19990101
RETURN person.firstName || ' ' || person.lastName AS person_name,
       friend.firstName || ' ' || friend.lastName AS friend_name

รูปแบบ (person:Person)-[:knows]-(friend:Person) จะแสดงโครงสร้างความสัมพันธ์ที่ตรงกัน ตัวแปรจะผูกสองคนนี้ไว้ เพื่อให้คําค้นหาสามารถกรองและคืนค่าคุณสมบัติของพวกเขาได้

พื้นฐาน GQL

แนวคิดเหล่านี้เป็นรากฐานของ GQL:

  • กราฟ ประกอบด้วยโหนดและขอบที่มีป้ายกํากับและคุณสมบัติ
  • ประเภทกราฟ จะกําหนดประเภทโหนด ประเภทขอบ และข้อจํากัดที่อนุญาตในกราฟอย่างเป็นทางการ
  • คําสั่งค้นหา ใช้คําสั่งเช่น MATCH, FILTER, และ RETURN เพื่อประมวลผลข้อมูลและสร้างผลลัพธ์
  • รูปแบบจะ อธิบายโครงสร้างกราฟที่ตรงกัน
  • นิพจน์ คํานวณ แปลง และเปรียบเทียบค่าต่าง ๆ
  • พรีดิเคต เป็นนิพจน์บูลีนที่ใช้ทดสอบเงื่อนไข
  • ประเภทค่า กําหนดประเภทของค่าที่คําค้นสามารถประมวลผลและคุณสมบัติของกราฟสามารถเก็บได้

เข้าใจข้อมูลกราฟ

ในการทํางานกับ GQL คุณต้องเข้าใจโครงสร้างกราฟคุณสมบัติที่มีป้ายกํากับซึ่งภาษานั้นค้นหา

โหนดและขอบ: บล็อกการสร้าง

กราฟคุณสมบัติที่มีป้ายกํากับประกอบด้วยองค์ประกอบกราฟสองประเภท:

  • โหนด โดยทั่วไปแทนสิ่งมีชีวิต เช่น บุคคล องค์กร โพสต์ หรือผลิตภัณฑ์
  • ขอบหมายถึง การเชื่อมต่อระหว่างโหนด เช่น บุคคลที่รู้จักกันหรือทํางานในบริษัท

แต่ละองค์ประกอบของกราฟมีอัตลักษณ์ภายใน ป้ายกํากับหนึ่งหรือมากกว่า และชุดคุณสมบัติ ป้ายกํากับใช้จัดประเภทองค์ประกอบ เช่น Person หรือ knows. คุณสมบัติคือคู่ชื่อ-ค่า เช่น firstName: 'Alice' หรือ birthday: 19730108u. ในกราฟ เส้นเชื่อมจะมีป้ายกํากับเพียงหนึ่งเดียวเสมอ

แต่ละขอบเชื่อมต่อสองโหนด: ต้นทางและเป้าหมาย ทิศทางขอบเป็นส่วนหนึ่งของโครงสร้างกราฟ ตัวอย่างเช่น workAt ขอบสามารถเชื่อม Person จุดกําเนิดกับ Company เป้าหมายได้

Note

กราฟในปัจจุบันยังไม่รองรับการสร้างขอบที่ไม่มีทิศทาง คุณสามารถสอบถามขอบที่มีทิศทางที่มีอยู่ในทิศทางใดก็ได้โดยใช้รูปแบบขอบที่มีทิศทางใดก็ได้ เช่น -[:knows]-.

กราฟมีรูปแบบที่ดี: ทุกขอบเชื่อมต่อโหนดสองโหนดที่อยู่ในกราฟเดียวกัน

แบบจําลองกราฟและชนิดกราฟ

โมเดลกราฟ Fabric กําหนดประเภทโหนด ประเภทขอบ คุณสมบัติ การแมปต้นทาง และคีย์ที่มีในกราฟ มันระบุว่าแถวในตารางต้นทางใดจะกลายเป็นโหนดและขอบ และองค์ประกอบเหล่านั้นเชื่อมต่อกันอย่างไร สําหรับคําแนะนําการสร้างแบบจําลอง ดูที่ การออกแบบกราฟสคีมา

มาตรฐาน GQL ใช้ ประเภทกราฟ เพื่ออธิบายประเภทโหนดที่อนุญาต ประเภทขอบ คุณสมบัติ และข้อจํากัดอย่างเป็นทางการ ประเภทกราฟเป็นส่วนที่อยู่ในระดับภาษาของโครงสร้างที่แทนโดยโมเดลกราฟ Fabric แต่ Graph ยังไม่รองรับการประกาศประเภทกราฟ GQL โดยตรง สําหรับไวยากรณ์และแนวคิดอย่างเป็นทางการ ดูที่ GQL graph types

ตัวอย่างกราฟที่ใช้ในคู่มือนี้

ตัวอย่างใช้ ชุดข้อมูลตัวอย่างเครือข่ายสังคม ซึ่งประกอบด้วยบุคคล สถานที่ องค์กร ข้อความ แท็ก และขอบที่เชื่อมโยงพวกเขา

กราฟตัวอย่างเชื่อมโยงพื้นที่เหล่านี้:

  • ผู้คนรู้จักกัน ทํางานในบริษัท และเรียนมหาวิทยาลัย
  • เมือง ประเทศ หรือภูมิภาค และทวีปต่าง ๆ ล้วนเป็นลําดับชั้นทางภูมิศาสตร์
  • ฟอรั่มมีโพสต์ และผู้คนก็สร้างโพสต์และแสดงความคิดเห็น
  • แท็กช่วยจัดหมวดหมู่เนื้อหาและแสดงถึงความสนใจของผู้คน

แผนภาพที่แสดงเค้าร่างเครือข่ายสังคมออนไลน์

สําหรับโครงสร้างตัวอย่างฉบับเต็ม ดูตัวอย่างสคีมาเครือข่ายสังคม สําหรับแนวคิดทั่วไปเกี่ยวกับกราฟ ดูที่ กราฟคุณสมบัติที่มีป้ายกํากับ

คิวรี GQL แรกของคุณ

ตอนนี้คุณเข้าใจพื้นฐานของกราฟแล้ว มาดูวิธีการคิวรีข้อมูลกราฟโดยใช้ GQL กัน ตัวอย่างเหล่านี้สร้างจากเรียบง่ายไปจนถึงซับซ้อน ซึ่งแสดงให้คุณเห็นว่าวิธีการของ GQL ทําให้การคิวรีกราฟใช้งานง่ายและมีประสิทธิภาพอย่างไร

เริ่มต้นอย่างง่าย: ค้นหาทุกคน

เริ่มต้นด้วยคิวรีพื้นฐานที่เป็นไปได้มากที่สุด ค้นหาชื่อ (ชื่อ นามสกุล) ของบุคคล:Personทั้งหมดในกราฟ

MATCH (p:Person)
RETURN p.firstName, p.lastName

คิวรีนี้จะทํางานดังนี้:

  1. MATCH ค้นหาโหนดทั้งหมดที่มี Personป้ายชื่อ
  2. RETURN แสดงชื่อและนามสกุลของชื่อเหล่านั้น

เพิ่มการกรอง: ค้นหาบุคคลที่ระบุ

ตอนนี้ค้นหาคนที่มีความเฉพาะเจาะจง ในกรณีนี้ค้นหาทุกคนที่มีชื่อว่าอลิซและแสดงชื่อและวันเกิดของพวกเขา

MATCH (p:Person)
FILTER p.firstName = 'Alice'
RETURN p.firstName, p.lastName, p.birthday

คิวรีนี้จะทํางานดังนี้:

  1. MATCH ค้นหาโหนดทั้งหมด (p) ที่มีป้ายชื่อ Person
  2. FILTER nodes (p) ที่มีชื่อแรกคือ Alice
  3. RETURN แสดงชื่อ นามสกุล และวันเกิดของพวกเขา

โครงสร้างคิวรีพื้นฐาน

คิวรี GQL พื้นฐานทั้งหมดเป็นไปตามรูปแบบที่สอดคล้องกัน: ลําดับคําสั่งที่ทํางานร่วมกันเพื่อค้นหา กรอง และส่งกลับข้อมูล คิวรีส่วนใหญ่เริ่มต้นด้วย MATCH เพื่อค้นหารูปแบบในกราฟและลงท้ายด้วย RETURN เพื่อระบุผลลัพธ์

ต่อไปนี้เป็นแบบสอบถามง่ายๆ ที่ค้นหาคู่ของคนที่รู้จักกันและมีวันเกิดเดียวกัน แล้วส่งกลับจํานวนทั้งหมดของคู่เพื่อนเหล่านั้น

MATCH (n:Person)-[:knows]-(m:Person)
FILTER n.birthday = m.birthday
RETURN count(*) AS same_age_friends

คิวรีนี้จะทํางานดังนี้:

  1. MATCH ค้นหาคู่ทั้งหมดของ Person โหนดที่รู้จักกันและกัน
  2. FILTER ช่วยให้คู่ที่ทั้งสองมีวันเกิดเดียวกัน
  3. RETURN นับจํานวนคู่เพื่อนดังกล่าวที่มีอยู่

เคล็ดลับ

คุณยังสามารถกรองโดยตรงในรูปแบบโดยการเพิ่ม WHERE clause ตัวอย่างเช่น MATCH (n:Person WHERE n.birthday < 19900101) จับคู่เฉพาะ Person โหนดที่มี birthday ค่าก่อนปี 1990 เท่านั้น

GQL สนับสนุนข้อคิดเห็นของบรรทัดรูปแบบ // C ข้อคิดเห็นบรรทัดสไตล์ -- SQL และบล็อกข้อคิดเห็นแบบ C-style /* */

คําชี้แจงทั่วไป

  • MATCH: ระบุรูปแบบกราฟที่จะค้นหา - นี่คือที่ที่คุณกําหนดโครงสร้างของข้อมูลที่คุณสนใจ
  • LET: กําหนดตัวแปรใหม่หรือค่าที่คํานวณโดยอิงจากข้อมูลที่ตรงกัน และเพิ่มคอลัมน์ที่ได้รับลงในผลลัพธ์
  • FOR: ขยายรายการเป็นแถว โดยมีตําแหน่งออฟเซ็ตแบบศูนย์หรือตําแหน่งลําดับหนึ่งแบบเลือกได้
  • CALL: รันคําสั่งย่อยแบบอินไลน์สําหรับแต่ละแถวอินพุตและเพิ่มคอลัมน์ที่ส่งกลับจากคําสั่งย่อยนั้น
  • FILTER: จํากัดผลลัพธ์ให้แคบลงโดยใช้เงื่อนไข - ลบแถวที่ไม่ตรงตามเกณฑ์
  • ORDER BY: จัดเรียงข้อมูลที่กรอง - ช่วยจัดระเบียบผลลัพธ์ตามฟิลด์อย่างน้อยหนึ่งฟิลด์
  • OFFSET และ LIMIT: จํากัดจํานวนแถวที่ส่งคืน ซึ่งมีประโยชน์สําหรับการแบ่งหน้าหรือการค้นหา k-top k
  • RETURN: ระบุผลลัพธ์สุดท้าย—กําหนดข้อมูลที่ควรรวมอยู่ในชุดผลลัพธ์และทําการรวม
  • NEXT: เริ่มขั้นตอนการค้นหาใหม่โดยใช้คอลัมน์ที่คืนมาจากขั้นตอนก่อนหน้า

คําสั่งทํางานร่วมกันอย่างไร

คําสั่ง GQL สร้างไปป์ไลน์ โดยแต่ละคําสั่งจะประมวลผลผลลัพธ์ของคําสั่งก่อนหน้า การดําเนินการตามลําดับนี้ทําให้การสืบค้นง่ายต่อการอ่านและแก้ไขข้อบกพร่อง เนื่องจากลําดับการดําเนินการตรงกับลําดับการอ่าน

ประเด็นสําคัญ:

  • คําสั่งดําเนินการตามลําดับอย่างมีประสิทธิภาพ
  • แต่ละคําสั่งจะแปลงข้อมูลและส่งต่อไปยังคําสั่งถัดไป
  • กระบวนการนี้สร้างโฟลว์ข้อมูลที่ชัดเจนและคาดการณ์ได้ซึ่งลดความซับซ้อนของคิวรี
  • NEXT เริ่มขั้นตอนการสืบค้นใหม่ เฉพาะคอลัมน์ที่ฉายโดยคําสั่งก่อนหน้า RETURN เท่านั้นที่จะพร้อมใช้งานในขั้นตอนถัดไป
  • UNION, UNION DISTINCT, และ UNION ALL รวมผลลัพธ์ของบล็อกคําสั่งค้นหาที่สมบูรณ์

Note

คําสั่งมีลําดับตรรกะที่กําหนดไว้ เขียนคําสั่งสืบค้นตามการไหลของข้อมูลนี้ แทนที่จะพึ่งพากลยุทธ์การดําเนินการทางกายภาพเฉพาะ

ตัวอย่างขององค์ประกอบคําสั่ง

คําค้นหา GQL ต่อไปนี้จะค้นหาบุคคล 10 คนแรกที่ทํางานในบริษัทที่มี "Air" อยู่ในชื่อ จัดเรียงตามชื่อเต็ม และส่งคืนชื่อเต็มพร้อมกับชื่อบริษัท

-- Data flows: Match → Let → Filter → Order → Limit → Return
MATCH (p:Person)-[:workAt]->(c:Company)           -- Input: unit table, Output: (p, c) table
LET fullName = p.firstName || ' ' || p.lastName   -- Input: (p, c) table, Output: (p, c, fullName) table
FILTER c.name CONTAINS 'Air'                      -- Input: (p, c, fullName) table, Output: filtered table
ORDER BY fullName                                 -- Input: filtered table, Output: sorted table
LIMIT 10                                          -- Input: sorted table, Output: top 10 rows table
RETURN fullName, c.name AS companyName            -- Input: top 10 rows table
                                                  -- Output: projected (fullName, companyName) result table

คิวรีนี้จะทํางานดังนี้:

  1. MATCH ค้นหาคนที่ทํางานในบริษัท
  2. LET สร้างชื่อเต็มโดยการรวมชื่อและชื่อนามสกุล
  3. FILTER เก็บเฉพาะพนักงานของบริษัทที่มี "Air" ในชื่อบริษัทเท่านั้น
  4. ORDER BY เรียงลําดับตามชื่อเต็ม
  5. LIMIT รับผลลัพธ์ 10 รายการแรก
  6. RETURN ส่งกลับชื่อเต็มและชื่อบริษัท

ตัวแปรเชื่อมต่อข้อมูลของคุณ

ตัวแปร เช่น p, cและ fullName ในตัวอย่างก่อนหน้านี้ จะดําเนินการข้อมูลระหว่างคําสั่ง เมื่อคุณนําชื่อตัวแปรกลับมาใช้ใหม่ GQL จะทําให้แน่ใจว่าชื่อนั้นอ้างอิงถึงข้อมูลเดียวกันโดยอัตโนมัติ เพื่อสร้างเงื่อนไขการรวมที่มีประสิทธิภาพ ตัวแปรบางครั้งเรียกว่าตัวแปรการผูก

คุณสามารถจัดประเภทตัวแปรได้หลายวิธี:

โดยการรวมแหล่งข้อมูล:

  • ตัวแปรรูปแบบ - ผูกตามรูปแบบกราฟที่ตรงกัน
  • ตัวแปรปกติ - ผูกกับโครงสร้างภาษาอื่น

ชนิดตัวแปรของรูปแบบ:

  • ตัวแปรองค์ประกอบ - ผูกกับค่าการอ้างอิงองค์ประกอบของกราฟ
    • ตัวแปรโหนด - ผูกกับแต่ละโหนด
    • ตัวแปร Edge - ผูกกับขอบแต่ละด้าน
  • ตัวแปรเส้นทาง - ผูกกับค่าเส้นทางที่แสดงเส้นทางที่ตรงกัน

ตามระดับอ้างอิง:

  • ตัวแปร Singleton - ผูกกับค่าอ้างอิงองค์ประกอบแต่ละรายการจากรูปแบบ
  • ตัวแปรกลุ่ม - ผูกกับรายการค่าอ้างอิงขององค์ประกอบจากรูปแบบความยาวแปรผัน สําหรับรายละเอียด ดูที่ ฟังก์ชันรวม

ผลลัพธ์ของการดําเนินการและผลลัพธ์

เมื่อคุณเรียกใช้คิวรี คุณจะได้รับ ผลลัพธ์การดําเนินการ ที่ประกอบด้วย:

  • ผลลัพธ์ โดยปกติจะเป็นตารางผลลัพธ์ที่มีข้อมูลจากคําสั่งของคุณRETURN
  • ข้อมูลสถานะ ที่แสดงว่าคิวรีสําเร็จหรือไม่

ตารางผลลัพธ์

ตารางผลลัพธ์ - ถ้ามี คือผลลัพธ์ที่แท้จริงของการดําเนินการคิวรี

ตารางผลลัพธ์ประกอบด้วยข้อมูลเกี่ยวกับชื่อและชนิดของคอลัมน์ ลําดับชื่อคอลัมน์ที่ต้องการใช้สําหรับการแสดงผลลัพธ์ ไม่ว่าตารางจะถูกเรียงลําดับและ แถวจริงหรือไม่

Note

ถ้าการดําเนินการล้มเหลว จะไม่มีตารางผลลัพธ์รวมอยู่ในผลลัพธ์การดําเนินการ

ผลลัพธ์ที่ถูกละเว้น

GQL ยังกําหนดผลลัพธ์ที่ถูกละเว้นสําหรับคําสั่งที่ไม่เคยสร้างแถว โดยไม่ขึ้นกับข้อมูลหรือผลลัพธ์การประเมิน ผลลัพธ์ที่ถูกละเว้นจะมีรหัส 00001สถานะการเติมเต็มสําเร็จ

ผลลัพธ์ที่ถูกละเว้นจะแตกต่างจากตารางผลลัพธ์ที่ว่างเปล่า ตารางว่างหมายความว่ามีการประเมินคําสั่งที่สร้างแถวแต่ไม่ได้สร้างแถว Query API สามารถแทนผลลัพธ์ที่ถูกละเว้นด้วยชนิด NOTHINGผลลัพธ์ .

กราฟสงวนผลลัพธ์ที่ถูกละเว้นไว้สําหรับการรองรับคําสั่ง Future Data Definition Language (DDL) และ Data Manipulation Language (DML) คําสั่งค้นหาปัจจุบันจะสร้างผลลัพธ์ของตาราง รวมถึงตารางว่าง

ข้อมูลสถานะ

ในระหว่างการดําเนินการคิวรี กระบวนการจะตรวจสอบเงื่อนไขต่าง ๆ ที่น่าจดจํา เช่น ข้อผิดพลาดหรือคําเตือน แต่ละเงื่อนไขจะถูกบันทึกโดยวัตถุสถานะในข้อมูลสถานะของผลลัพธ์การดําเนินการ

ข้อมูลสถานะประกอบด้วยออบเจ็กต์สถานะหลักและรายการ (อาจว่างเปล่า) ของออบเจ็กต์สถานะอื่น ๆ วัตถุสถานะหลักจะมีอยู่เสมอและระบุว่าการดําเนินการคิวรีสําเร็จหรือล้มเหลว

วัตถุสถานะทุกตัวจะมีรหัสตัวอักษรและตัวเลขห้าตัวและคําอธิบายของเงื่อนไขที่บันทึกไว้

Query API ใช้รหัสสถานะหลักดังต่อไปนี้:

รหัสสถานะ API ความหมาย
00000 เสร็จสิ้นด้วยอย่างน้อยหนึ่งแถว
00001 การสําเร็จงานโดยตัดผลลัพธ์ออก สงวนไว้สําหรับการรองรับ DDL และ DML ในอนาคต
01000 เป็นคําเตือนหรือเงื่อนไขข้อมูล
02000 ขณะนี้ยังไม่มีแถวใดที่พร้อมใช้งานจากคําสั่งที่สร้างแถว
42000 ข้อผิดพลาดในการสืบค้นที่ผู้ใช้แก้ไขได้
50000 เป็นข้อผิดพลาดของระบบหรือที่ไม่ได้จัดประเภท

API จะรักษาสถานะ GQL มาตรฐานที่ _graphaneGqlStatus รายงานโดยเอนจินค้นหาในสมาชิกของระเบียนวินิจฉัย ตัวอย่างเช่น numeric overflow ใช้ canonical GQLSTATUS 22003ในขณะที่การหารด้วยศูนย์ใช้22012; ทั้งสองแสดงโดย 42000 ในช่องสาธารณะstatus.code

สําคัญ

ในโค้ดแอปพลิเคชัน ใช้ status.code สําหรับความสําเร็จกว้างและการจัดการข้อผิดพลาด ใช้การวินิจฉัย GQLSTATUS แบบมาตรฐานเมื่อคุณต้องการแยกแยะเงื่อนไขคําสั่งเฉพาะ อย่าทดสอบข้อความคําอธิบายเพราะมันอาจแตกต่างกันได้

นอกจากนี้ ออบเจ็กต์สถานะสามารถประกอบด้วยออบเจ็กต์สถานะพื้นฐานและเรกคอร์ดการวินิจฉัยที่มีข้อมูลเพิ่มเติมที่แสดงเงื่อนไขที่บันทึกไว้

ดูรหัสสถานะ GQL

แนวคิดและข้อความสําคัญ

ส่วนนี้ครอบคลุมถึงบล็อกการสร้างหลักที่คุณจําเป็นต้องเขียนคิวรี GQL ที่มีประสิทธิภาพ แนวคิดแต่ละแบบจะสร้างขึ้นเพื่อทักษะการเขียนคิวรีที่ใช้งานได้จริง

รูปแบบกราฟ: ค้นหาโครงสร้าง

รูปแบบกราฟจะอธิบายโหนด ขอบ และเส้นทางที่ต้องจับคู่ ผูกตัวแปรเมื่อคําสั่งในภายหลังต้องการอ้างอิงถึงองค์ประกอบที่ตรงกัน:

MATCH (person:Person)-[employment:workAt]->(company:Company)
RETURN person.firstName, company.name, employment.workFrom

วางพรีดิเคตแบบอินไลน์เมื่อกําหนดว่าโหนดหรือขอบใดสามารถเข้าร่วมในรูปแบบได้:

MATCH (person:Person WHERE person.firstName = 'Alice')
      -[:knows]->(friend:Person)
RETURN friend.firstName, friend.lastName

ใช้ตัวแปรซ้ําเพื่อกําหนดตําแหน่งแพทเทิร์นสองตําแหน่งเพื่อผูกกับองค์ประกอบเดียวกัน แยกรูปแบบด้วยเครื่องหมายจุลภาคเพื่อสร้างโครงสร้างกราฟขนาดใหญ่ขึ้น ใช้ตัวบ่งชี้ปริมาณ เช่น {1,4} การทําซ้ํารูปแบบขอบและจับคู่เส้นทางที่มีความยาวแปรผัน

โหมดเส้นทางใช้ซ้ําองค์ประกอบภายในเส้นทาง:

โหมดเส้นทาง พฤติกรรม
WALK อนุญาตให้มีโหนดและขอบที่ซ้ํากัน โหมดนี้เป็นค่าเริ่มต้น
TRAIL ป้องกันการเกิดขอบซ้ํา
SIMPLE ป้องกันการซ้ําโหนดยกเว้นโหนดแรกและโหนดสุดท้ายที่ใช้ร่วมกัน
ACYCLIC ป้องกันโหนดที่ซ้ํากันทั้งหมด

คํานําหน้าการค้นหาเส้นทางจะควบคุมว่าเส้นทางใดจะถูกส่งคืน ALL เป็นค่าเริ่มต้น ANY SHORTEST ส่งคืนเส้นทางที่สั้นที่สุดหนึ่งเส้นทางสําหรับแต่ละคู่ต้นทาง-ปลายทาง:

MATCH path = ANY SHORTEST
  (source:Person WHERE source.id = 123u)-[:knows]->{1,4}(target:Person)
RETURN target.id, path_length(path) AS hopCount

เงื่อนไขแบบอินไลน์จํากัดคุณสมบัติของเส้นทางก่อนการเลือกเส้นทาง การดําเนินการระดับ MATCH ... WHERE คําสั่งและหลังจาก FILTER นั้นเป็น postfilters ความแตกต่างนี้สามารถเปลี่ยนแปลง ANY SHORTEST ผลลัพธ์ได้

สําหรับความหมายของโหนด, ขอบ, เส้นทาง, คอมโพสิชัน, ตัวบ่งชี้ปริมาณ และการกําหนดตําแหน่งพรีดิเคต โปรดดูที่รูปแบบกราฟ GQL สําหรับข้อจํากัดเส้นทางปัจจุบัน ดูที่ ข้อจํากัดปัจจุบัน

คําชี้แจงหลัก

GQL มีชนิดคําสั่งเฉพาะที่ทํางานร่วมกันเพื่อประมวลผลข้อมูลกราฟของคุณทีละขั้นตอน การทําความเข้าใจคําสั่งเหล่านี้เป็นสิ่งจําเป็นสําหรับการสร้างคิวรีที่มีประสิทธิภาพ

MATCH ถ้อยแถลง

วากยสัมพันธ์:

MATCH <graph pattern>, <graph pattern>, ... [ WHERE <predicate> ]

คําสั่ง MATCH ใช้ข้อมูลป้อนเข้าและค้นหารูปแบบกราฟ ซึ่งจะรวมตัวแปรอินพุตกับตัวแปรรูปแบบและส่งออกชุดข้อมูลที่ตรงกันทั้งหมด

ตัวแปรอินพุตและเอาต์พุต:

-- Input: unit table (no columns, one row)
-- Pattern variables: p, c  
-- Output: table with (p, c) columns for each person-company match
MATCH (p:Person)-[:workAt]->(c:Company)

การกรองระดับคําสั่งโดยใช้ WHERE:

-- Filter pattern matches
MATCH (p:Person)-[:workAt]->(c:Company) WHERE p.lastName = c.name

คุณสามารถกรองรายการที่ตรงกันทั้งหมดโดยใช้WHERE วิธีการนี้หลีกเลี่ยงคําสั่งแยกต่างหากFILTER ด้วยคํานําหน้าการค้นหาเส้นทาง เช่น ANY SHORTEST, ระดับ WHERE คําสั่งจะถูกใช้หลังจากการเลือกเส้นทาง เงื่อนไขแบบอินไลน์จะจํากัดเส้นทางที่มีสิทธิ์เลือกแทน สําหรับข้อมูลเพิ่มเติม ดูที่ Place predicates ก่อนหรือหลังการเลือกเส้นทาง

การรวมโดยใช้ตัวแปรอินพุต:

เมื่อ MATCH ไม่ใช่คําสั่งแรก จะรวมข้อมูลป้อนเข้าที่มีการจับคู่รูปแบบ:

...
-- Input: table with 'targetCompany' column
-- Implicit join: targetCompany (equality join)
-- Output: table with (targetCompany, p, r) columns
MATCH (p:Person)-[r:workAt]->(targetCompany)

สําคัญ

กราฟรองรับการประกอบประโยคเชิงเส้นพื้นฐานและเต็มรูปแบบ รวมถึง NEXT. คุณยังสามารถรวมบล็อกคําสั่งค้นหากับ UNION, UNION DISTINCT, และ UNION ALL. EXCEPTการดําเนินการ , INTERSECT, และOTHERWISEเซตยังไม่ได้รับการสนับสนุน สําหรับข้อมูลเพิ่มเติม โปรดดูที่บทความเกี่ยวกับข้อจํากัดปัจจุบัน

ลักษณะการทํางานการรวมคีย์:

วิธี MATCH จัดการการเข้าร่วมข้อมูล:

  • ความเท่ากันของตัวแปร: ตัวแปรอินพุตรวมกับตัวแปรรูปแบบโดยใช้การจับคู่ความเท่ากัน
  • การรวมภายใน: แถวอินพุตที่ไม่มีรูปแบบที่ตรงกันจะถูกละทิ้ง ใช้สําหรับ OPTIONAL MATCH ลักษณะการทํางานการรวมจากภายนอกด้านซ้าย
  • ลําดับการกรอง: ตัวกรองระดับ WHERE คําสั่งหลังจากจับคู่รูปแบบและเลือกเส้นทางเสร็จสิ้น
  • การประกอบรูปแบบ: ตัวแปรที่ใช้ร่วมกันจะจํากัดรูปแบบให้อยู่ในองค์ประกอบเดียวกัน รูปแบบที่ไม่เชื่อมต่อกันจะสร้างผลคูณแบบคาร์ทีเซียน

สําคัญ

รูปแบบที่ไม่เชื่อมต่อกันนั้นถูกต้อง แต่ผลคูณคาร์ทีเซียนของมันสามารถสร้างแถวได้หลายแถว ใช้ตัวแปรที่ใช้ร่วมกันเมื่อรูปแบบควรอ้างอิงถึงองค์ประกอบกราฟเดียวกัน

เชื่อมโยงรูปแบบที่มีตัวแปรร่วมกัน:

-- Shared variable 'p' joins the two patterns
-- Output: people with both workplace and residence data
MATCH (p:Person)-[:workAt]->(c:Company), 
      (p)-[:isLocatedIn]->(city:City)

OPTIONAL MATCH ถ้อยแถลง

วากยสัมพันธ์:

OPTIONAL MATCH <graph pattern> [ WHERE <predicate> ]

OPTIONAL MATCH ทํางานเหมือน MATCH แต่ใช้ตรรกะการรวมด้านซ้าย (left-outer-join) ถ้ารูปแบบไม่ตรงกันสําหรับแถวอินพุต คิวรีจะเก็บแถวที่มี NULL ค่าสําหรับตัวแปรที่ไม่ตรงกันแทนที่จะละทิ้ง

ตัวอย่าง:

-- Find all people and, if available, their workplace
MATCH (p:Person)
OPTIONAL MATCH (p)-[:workAt]->(c:Company)
RETURN p.firstName, p.lastName, c.name AS company_name

บุคคลที่ไม่ได้ทํางานในบริษัทใดๆ ยังคงปรากฏในผลลัพธ์ด้วย NULL สําหรับcompany_name

เคล็ดลับ

ใช้OPTIONAL MATCHเมื่อคุณต้องการรวมเอนทิตีที่อาจไม่มีความสัมพันธ์เฉพาะ คล้ายกับ SQL LEFT JOIN

LET ถ้อยแถลง

วากยสัมพันธ์:

LET <variable> = <expression>, <variable> = <expression>, ...

คําสั่ง LET จะสร้างตัวแปรที่คํานวณและเปิดใช้งานการแปลงข้อมูลภายในไปป์ไลน์คิวรีของคุณ

การสร้างตัวแปรพื้นฐาน:

MATCH (p:Person)
LET fullName = p.firstName || ' ' || p.lastName
RETURN *
LIMIT 1000

การคํานวณที่ซับซ้อน:

MATCH (p:Person)
LET adjustedAge = 2000 - (p.birthday / 10000),
    fullProfile = p.firstName || ' ' || p.lastName || ' (' || p.gender || ')'
RETURN *
LIMIT 1000

ลักษณะการทํางานหลัก:

  • กลไกจัดการคิวรีจะประเมินนิพจน์สําหรับแถวอินพุตทั้งหมด
  • ผลลัพธ์จะกลายเป็นคอลัมน์ใหม่ในตารางผลลัพธ์
  • ตัวแปรสามารถอ้างอิงได้เฉพาะตัวแปรที่มีอยู่จากคําสั่งก่อนหน้านี้เท่านั้น
  • การกําหนดหลายรายการในคําสั่งเดียวกัน LET จะใช้ขอบเขตอินพุตเดียวกัน ดังนั้นการกําหนดหนึ่งจึงไม่สามารถอ้างอิงการกําหนดอื่นจากคําสั่งนั้นได้

FOR ถ้อยแถลง

วากยสัมพันธ์:

FOR <variable> IN <list_expression>
  [ WITH OFFSET <offset_variable> | WITH ORDINALITY <ordinality_variable> ]

คําสั่งจะ FOR ขยายรายการเป็นแถว สําหรับแต่ละแถวอินพุต มันจะปล่อยหนึ่งแถวเอาต์พุตสําหรับแต่ละองค์ประกอบในรายการและผูกองค์ประกอบนั้นกับตัวแปรที่ระบุ ตัวแปรอื่น ๆ จากแถวอินพุตยังคงใช้งานได้

ใช้สําหรับ WITH OFFSET ผูกดัชนีที่มีฐานเป็นศูนย์ หรือใช้ WITH ORDINALITY สําหรับผูกตําแหน่งที่มีฐานเดียว

LET cities = ['Seattle', 'London', 'Tokyo']
FOR city IN cities WITH ORDINALITY position
RETURN city, position

คําค้นหานี้จะคืนค่าหนึ่งแถวสําหรับแต่ละเมือง ค่าคือ position1, 2, และ 3. ถ้าคุณแทนที่ WITH ORDINALITY position ด้วย WITH OFFSET positionค่าคือ 0, 1, และ 2.

นิพจน์ต้นทางต้องประเมินผลเป็นรายการ ค่าที่ไม่ใช่รายการจะทําให้การค้นหาล้มเหลว

CALL ถ้อยแถลง

ใช้สําหรับ CALL รันคําสั่งย่อยแบบอินไลน์สําหรับแต่ละแถวอินพุต:

CALL {
  <query statements>
  RETURN <columns>
}

ตัวแปรที่อยู่ในขอบเขตอยู่แล้วจะมีอยู่โดยนัยภายในซับคิวรี จากตัวแปรที่สร้างภายในซับคิวรี จะมีเพียงคอลัมน์จากคําสั่งสุดท้าย RETURN เท่านั้นที่จะสามารถใช้งานได้ภายนอกซับคิวรี ตัวแปรที่สร้างภายในซับคิวรีแต่ไม่ได้ส่งคืนจะยังคงเป็นตัวกลาง

คําค้นหาย่อยที่เกี่ยวข้องต่อไปนี้คํานวณจํานวนนายจ้างสําหรับแต่ละบุคคล:

MATCH (p:Person)
CALL {
  MATCH (p)-[:workAt]->(company:Company)
  RETURN count(*) AS employerCount
}
RETURN p.firstName, p.lastName, employerCount
ORDER BY employerCount DESC

ordinary CALL ทําหน้าที่เหมือน inner join ที่ขึ้นกับกัน มันจะสร้างแถวผลลัพธ์หนึ่งแถวสําหรับทุกแถวที่ส่งกลับจากซับคิวรี หากซับคิวรีไม่คืนค่าแถว แถวด้านนอกที่เกี่ยวข้องจะไม่ถูกคืนค่า ถ้าส่งคืนหลายแถว แถวด้านนอกจะปรากฏหนึ่งครั้งสําหรับแต่ละแถวของซับคิวรี

ตัวอย่างก่อนหน้านี้ count(*) จะคืนค่าหนึ่งแถวซับคิวรีเสมอเพราะใช้การรวมแบบไม่จัดกลุ่ม บุคคลที่ไม่มีนายจ้างที่จับคู่กันจึงมีemployerCount0

ใช้ OPTIONAL CALL เป็นการเชื่อมซ้ายที่ขึ้นกับผู้อื่น เมื่อซับคิวรีไม่คืนค่าแถวใด ๆ จะเก็บแถวนอกหนึ่งแถวไว้และตั้งค่าคอลัมน์ NULLซับคิวรีที่คืนเป็น เมื่อซับคิวรีคืนค่าหลายแถว จะสร้างหนึ่งแถวผลลัพธ์สําหรับแต่ละแถวซับคิวรี

MATCH (p:Person)
OPTIONAL CALL {
  MATCH (p)-[:workAt]->(company:Company)
  RETURN company.name AS companyName
}
RETURN p.firstName, p.lastName, companyName

คุณสามารถซ้อนซับคิวรีแบบอินไลน์ CALL ได้ ซับคิวรีที่ซ้อนกันสามารถอ้างอิงตัวแปรจากขอบเขตการค้นหาที่ล้อมรอบได้

สําคัญ

จบแต่ละตัวประกอบแบบอินไลน์ CALL ด้วย RETURN. กราฟไม่รองรับการเรียกโปรซีเยอร์ที่ตั้งชื่อหรือรายการนําเข้าตัวแปรที่ชัดเจน เช่น CALL (p) { ... }.

FILTER ถ้อยแถลง

วากยสัมพันธ์:

FILTER [ WHERE ] <predicate>

คําสั่ง FILTER ให้การควบคุมอย่างแม่นยําว่าข้อมูลใดดําเนินการผ่านไปป์ไลน์คิวรีของคุณ

การกรองพื้นฐาน:

MATCH (p:Person)
FILTER p.birthday < 19980101 AND p.gender = 'female'
RETURN *

เงื่อนไขเชิงตรรกะที่ซับซ้อน:

MATCH (p:Person)
FILTER (p.gender = 'male' AND p.birthday < 19940101) 
  OR (p.gender = 'female' AND p.birthday < 19990101)
  OR p.browserUsed = 'Edge'
RETURN *

รูปแบบการกรอง Null-aware:

ใช้รูปแบบเหล่านี้เพื่อจัดการค่า null อย่างปลอดภัย:

  • ตรวจสอบค่า: p.firstName IS NOT NULL - มีชื่อ
  • ตรวจสอบข้อมูล: p.id > 0 - รหัสที่ถูกต้อง
  • จัดการข้อมูลที่ขาดหายไป: NOT coalesce(p.locationIP, '10.x.x.x') STARTS WITH '10.x.x.x' - ไม่ได้เชื่อมต่อจากเครือข่ายภายใน
  • รวมเงื่อนไข: ใช้กับ AND/OR การตรวจสอบ null อย่างชัดเจนสําหรับตรรกะที่ซับซ้อน

ข้อควรระวัง

โปรดจําไว้ว่าเงื่อนไขที่เกี่ยวข้องกับค่า null จะส่งกลับ UNKNOWNซึ่งกรองแถวเหล่านั้นออก ใช้การตรวจสอบอย่างชัดเจน IS NULL เมื่อคุณต้องการตรรกะการรวม null

ORDER BY ถ้อยแถลง

วากยสัมพันธ์:

ORDER BY <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ],
         <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ], ...

การเรียงลําดับหลายระดับด้วยนิพจน์ที่คํานวณ:

MATCH (p:Person)
RETURN *
ORDER BY p.firstName DESC,               -- Primary: by first name (Z-A)
         p.birthday ASC,                 -- Secondary: by age (oldest first)
         p.id DESC                       -- Tertiary: by ID (highest first)

การจัดการ Null ในการเรียงลําดับ:

MATCH (p:Person)
RETURN p.firstName, p.birthday
ORDER BY p.birthday DESC NULLS LAST, p.firstName ASC

เรียงลําดับรายละเอียดลักษณะการทํางาน:

ทําความเข้าใจวิธีการ ORDER BY ทํางาน:

  • กลไกจัดการคิวรีจะประเมินนิพจน์สําหรับแต่ละแถว จากนั้นผลลัพธ์จะกําหนดลําดับแถว
  • คีย์การเรียงลําดับหลายคีย์จะสร้างการจัดลําดับแบบลําดับชั้น (หลัก รอง ภูมิศาสตร์ และอื่น ๆ)
  • NULLS FIRST วางค่าว่างไว้ก่อนค่าที่ไม่เป็นศูนย์ NULLS LAST วางไว้หลังค่าที่ไม่เป็นศูนย์
  • การวาง null ไม่ขึ้นกับทิศทางการเรียงลําดับ ถ้าคุณไม่ได้ระบุลําดับ null NULLS LAST จะเป็นค่าเริ่มต้นสําหรับทั้งและASCDESC
  • ASC (จากน้อยไปหามาก) เป็นลําดับเริ่มต้น และคุณต้องระบุ DESC อย่างชัดเจน (จากมากไปหาน้อย)
  • คุณสามารถเรียงลําดับตามค่าจากการคํานวณ ไม่ใช่แค่คุณสมบัติที่เก็บไว้เท่านั้น
ข้อกําหนดการจัดเรียง ลําดับที่เกิดขึ้น
ASC หรือ ASC NULLS LAST ค่าที่ไม่เป็นค่า null เรียงจากน้อยไปมาก ตามด้วยค่าที่เป็นค่า null
ASC NULLS FIRST ค่า null ตามด้วยค่าที่ไม่เป็นค่า null ตามลําดับจากน้อยไปน้อย
DESC หรือ DESC NULLS LAST ค่าที่ไม่เป็นศูนย์ตามลําดับจากมากไปน้อย ตามด้วยค่าที่เป็นศูนย์
DESC NULLS FIRST ค่าที่เป็นค่า null ตามด้วยค่าที่ไม่เป็นค่า (non-null) ตามลําดับจากมากไปน้อย

ข้อควรระวัง

เฉพาะคําสั่งต่อไปนี้ ทันที เท่านั้นที่สามารถดูลําดับ ORDER BY การจัดเรียงที่สร้างขึ้นได้ ดังนั้น ORDER BY ตามด้วย RETURN * ไม่ได้สร้างผลลัพธ์ที่เรียงลําดับ

เปรียบเทียบ:

MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
ORDER BY r.creationDate DESC
/* intermediary result _IS_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
/* final result _IS_ _NOT_ guaranteed to be ordered here  */

กับ:

MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
/* intermediary result _IS_ _NOT_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
ORDER BY r.creationDate DESC
/* final result _IS_ guaranteed to be ordered here              */

ความแตกต่างนี้มีผลกระทบทันทีสําหรับคิวรี "Top-k": LIMIT ต้องทําตาม ORDER BY คําสั่งที่สร้างลําดับการจัดเรียงตามที่ต้องการเสมอ

OFFSET และ LIMIT ข้อความ

วากยสัมพันธ์:

  OFFSET <offset> [ LIMIT <limit> ]
| LIMIT <limit>

รูปแบบทั่วไป:

-- Basic top-N query
MATCH (p:Person)
RETURN *
ORDER BY p.id DESC
LIMIT 10                                 -- Top 10 by ID

สําคัญ

เพื่อให้ได้ผลลัพธ์การแบ่งหน้าที่สามารถคาดการณ์ได้ โปรดใช้ ORDER BY ก่อน OFFSET และ LIMIT เพื่อให้แน่ใจว่าแถวที่เรียงลําดับในคิวรีต่าง ๆ สอดคล้องกัน

RETURN: การคาดการณ์ผลลัพธ์พื้นฐาน

วากยสัมพันธ์:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
[ ORDER BY <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]

คําสั่ง RETURN สร้างผลลัพธ์สุดท้ายของคิวรีโดยการระบุข้อมูลที่ปรากฏในตารางผลลัพธ์

ผลลัพธ์พื้นฐาน:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name, 
       p.birthday, 
       c.name

ใช้นามแฝงเพื่อความชัดเจน:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS first_name, 
       p.lastName AS last_name,
       c.name AS company_name

รวมกับการเรียงลําดับและ top-k:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name, 
       p.birthday AS birth_year, 
       c.name AS company
ORDER BY birth_year ASC
LIMIT 10

ทําซ้ําการจัดการโดยใช้ DISTINCT:

-- Remove duplicate combinations
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN DISTINCT p.gender, p.browserUsed, p.birthday AS birth_year
ORDER BY p.gender, p.browserUsed, birth_year

รวมกับการรวม:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN count(DISTINCT p) AS employee_count

RETURN มี GROUP BY: การฉายภาพผลลัพธ์ที่จัดกลุ่มแล้ว

วากยสัมพันธ์:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
GROUP BY <variable>, <variable>, ...
[ ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]

ใช้ GROUP BY เพื่อจัดกลุ่มแถวตามค่าที่ใช้ร่วมกันและคํานวณฟังก์ชันการรวมภายในแต่ละกลุ่ม

การจัดกลุ่มพื้นฐานที่มีการรวม:

MATCH (p:Person)-[:workAt]->(c:Company)
LET companyId = c.id, companyName = c.name
RETURN companyId,
       companyName,
       count(*) AS employeeCount,
       avg(p.birthday) AS avg_birth_year
GROUP BY companyId, companyName
ORDER BY employeeCount DESC

การจัดกลุ่มแบบหลายคอลัมน์:

MATCH (p:Person)
LET gender = p.gender
LET browser = p.browserUsed
RETURN gender,
       browser,
       count(*) AS person_count,
       avg(p.birthday) AS avg_birth_year,
       min(p.creationDate) AS first_joined,
       max(p.id) AS highest_id
GROUP BY gender, browser
ORDER BY avg_birth_year DESC
LIMIT 10

Note

สําหรับการรวมแนวนอนบนรูปแบบความยาวแปรผัน ดูที่ฟังก์ชันรวม

ค่าและชนิดค่า

ค่าของ GQL ได้แก่ Boolean, string, numeric, temporal, list, node, edge, path, null และ nothing ประเภทจะเป็น null เว้นแต่คุณจะระบุNOT NULL คุณสมบัติใช้ชุดย่อยที่รองรับของระบบค่าคําค้นทั้งหมด

RETURN 42 AS integerValue,
       'Alice' AS stringValue,
       TRUE AS booleanValue,
       [1, 2, 3] AS listValue

การเปรียบเทียบกับการประเมินค่า null เพื่อ UNKNOWN; การใช้งาน IS NULL และ IS NOT NULL การทดสอบ null การดําเนินการเชิงตัวเลขสามารถแปลงโดยนัยระหว่างประเภทตัวเลขที่เข้ากันได้

Note

ไม่ใช่ทุกประเภทค่าของ GQL จะรองรับในทุกบริบทของ Graph สําหรับข้อจํากัดคุณสมบัติและคําสั่งค้นหาในปัจจุบัน ดูที่ ประเภทข้อมูล

สําหรับไวยากรณ์ตามตัวอักษร พฤติกรรมการเปรียบเทียบ การแปลงประเภท และลําดับชั้นของประเภท ดูที่ค่าและประเภทค่าของ GQL

นิพจน์

นิพจน์จะคํานวณ เปรียบเทียบ รวม และแปลงค่าต่าง ๆ รูปแบบที่พบบ่อยได้แก่ การอ้างอิงคุณสมบัติ ตัวดําเนินการทางเลขคณิตและตรรกะ พรีดิเคต การเรียกฟังก์ชัน นิพจน์ง่าย CASE ๆ และซับคิวรี:

MATCH (person:Person)
FILTER person.birthday < 19900101
RETURN person.firstName,
       CASE person.gender
         WHEN 'female' THEN 'F'
         WHEN 'male' THEN 'M'
         ELSE 'Other'
       END AS genderCode

GQL ใช้ตรรกะสามค่า: นิพจน์บูลีนสามารถประเมินค่าเป็น TRUE, FALSE, หรือ UNKNOWN. A FILTER จะเก็บเฉพาะแถวที่มีพรีดิเคตของมันเป็นTRUE

รวมฟังก์ชัน เช่น COUNT, SUM, AVG, MIN, และ MAX สรุปแถว ลิสต์พรีดิเคต เช่น ALL, ANY, NONE, และ SINGLE ประเมินพรีดิเคตสําหรับองค์ประกอบลิสต์ คําสั่งย่อยในรูปแบบ EXISTS กระบวนการทดสอบว่าคําสั่งที่แทรกซ้อนจะคืนค่าแถวหรือไม่

สําหรับพฤติกรรมของโอเปอเรเตอร์ พรีดิเคต การรวม และฟังก์ชันที่สมบูรณ์ ดูที่ นิพจน์ พรีดิเคต และฟังก์ชัน GQL สําหรับตัวอย่างการกรองและการจัดกลุ่มแบบเฉพาะงาน ดูที่ กรองและรวบรวมข้อมูลกราฟ

เทคนิคการคิวรีขั้นสูง

ส่วนนี้ครอบคลุมรูปแบบและเทคนิคที่ซับซ้อนสําหรับการสร้างคิวรีกราฟที่ซับซ้อนและมีประสิทธิภาพ รูปแบบเหล่านี้นอกเหนือจากการใช้คําสั่งพื้นฐานเพื่อช่วยให้คุณสร้างคิวรีการวิเคราะห์ที่มีประสิทธิภาพ

องค์ประกอบหลายคําสั่งที่ซับซ้อน

สําคัญ

กราฟสนับสนุนองค์ประกอบแบบพื้นฐานและเชิงเส้นเต็ม EXCEPTการดําเนินการ , INTERSECT, และOTHERWISEเซตยังไม่ได้รับการสนับสนุน สําหรับข้อมูลเพิ่มเติม โปรดดูที่บทความเกี่ยวกับข้อจํากัดปัจจุบัน

การทําความเข้าใจวิธีการเขียนคิวรีที่ซับซ้อนอย่างมีประสิทธิภาพเป็นสิ่งสําคัญสําหรับการคิวรีกราฟขั้นสูง

UNION และ UNION ALL

ใช้ UNION, UNION DISTINCT, หรือ UNION ALL เพื่อรวมผลลัพธ์จากบล็อกคิวรีเชิงเส้นสองบล็อกขึ้นไป:

<query block>
UNION [ DISTINCT | ALL ]
<query block>

-- Combine results from two separate pattern matches
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS name, c.name AS affiliation
UNION DISTINCT
MATCH (p:Person)-[:studyAt]->(u:University)
RETURN p.firstName AS name, u.name AS affiliation

เปลือย UNION เทียบเท่ากับ UNION DISTINCT; ทั้งสองจะลบแถวที่ซ้ํากัน UNION ALL เก็บแถวทั้งหมด รวมถึงรายการที่ซ้ํากัน

แต่ละบล็อกคําสั่งค้นหาต้องคืนค่าชุดชื่อคอลัมน์เดียวกัน ลําดับคอลัมน์อาจแตกต่างกันระหว่างบล็อก และชนิดข้อมูลต้องเข้ากันได้

NEXT

ใช้เพื่อ NEXT รันขั้นตอนการสืบค้นอีกขั้นตอนหนึ่งกับตารางที่ส่งคืนจากขั้นตอนก่อนหน้า:

<query stage>
RETURN <columns>
NEXT
<query stage>

คําค้นหาต่อไปนี้จะค้นหาพนักงานและบริษัทของพวกเขา จากนั้นใช้โหนดพนักงานที่คืนมาในแพตเทิร์นแมตช์อื่น:

MATCH (person:Person)-[:workAt]->(company:Company)
RETURN person, company.name AS companyName
NEXT
MATCH (person)-[:isLocatedIn]->(city:City)
RETURN person.firstName AS employee, companyName, city.name AS city

เฉพาะคอลัมน์ที่ส่งคืนโดยขั้นตอนก่อนหน้าเท่านั้นที่อยู่ในขอบเขตหลังจากNEXT คุณสามารถใช้ตัวคั่นหลาย NEXT ตัวเพื่อสร้างลําดับขั้นตอนการสืบค้นที่ยาวขึ้น

ทั้งสองขั้นตอนสามารถมีบล็อกคําสั่งค้นหารวมกันได้ สหภาพจะถูกประเมินภายในขั้นตอนก่อนที่ผลลัพธ์ของขั้นตอนจะข้าม NEXT ขอบเขต ถ้า A, B, และ แทน C บล็อก A UNION B NEXT C การค้นหา กลุ่มเป็น (A UNION B) NEXT C, ขณะที่ A NEXT B UNION C กลุ่มเป็น A NEXT (B UNION C).

คำสั่งแบบมีเงื่อนไข

ใช้คําสั่งเงื่อนไขเพื่อส่งแถวขาเข้าแต่ละแถวไปยังกิ่งแรกที่พรีดิเคตประเมินค่าเป็น TRUE:

WHEN <predicate> THEN <linear query statement or { query statements }>
[ WHEN <predicate> THEN <linear query statement or { query statements }> ... ]
[ ELSE <linear query statement or { query statements }> ]

หากต้องการส่งแถวจากขั้นตอนการค้นหาก่อนหน้า ให้คืนค่าคอลัมน์ที่ต้องการและใช้ NEXT ก่อนคําสั่งเงื่อนไข:

MATCH (p:Person)
RETURN p.firstName AS name, p.birthday AS birthday
NEXT
WHEN birthday < 19800101u THEN
  RETURN name, 'Before 1980' AS era
WHEN birthday < 20000101u THEN
  RETURN name, '1980-1999' AS era
ELSE
  RETURN name, '2000 or later' AS era

WHENแต่ละพรีดิเคตต้องเป็นบูลีน เครื่องมือค้นหาจะประเมินพรีดิเคตตามลําดับสําหรับแต่ละแถวอินพุต พรีดิเคตที่ประเมินไปยัง FALSE หรือไม่ UNKNOWN เลือกสาขาของมัน หลังจากที่พรีดิเคตประเมินค่าไปยัง TRUE, พรีดิเคตภายหลังและร่างสาขาที่ไม่ได้เลือกจะไม่ถูกประเมิน ถ้าไม่มีพรีดิเคตใดประเมินค่าไปยัง TRUE และไม่มี ELSE, แถวอินพุตจะไม่ถูกส่งคืน

คําพจน์และตัวสาขาสามารถอ้างอิงคอลัมน์จากขั้นตอนก่อนหน้าได้ กิ่งหนึ่งอาจเป็นคําสั่งเชิงเส้นเดียว หรือเป็นโปรซีเดอร์ซ้อนที่อยู่ในวงเล็บ ใช้ขั้นตอนซ้อนเมื่อสาขาต้องการหลายขั้นตอนหรือคําสั่ง เช่น CALL:

MATCH (p:Person)
RETURN p, p.firstName AS name
NEXT
WHEN p.gender = 'female' THEN {
  CALL {
    MATCH (p)-[:knows]->(friend:Person)
    RETURN count(*) AS friendCount
  }
  RETURN name, friendCount
}
ELSE
  RETURN name, 0u AS friendCount

แต่ละสาขามีขอบเขตท้องถิ่นของตนเอง สาขาพี่น้องจะไม่เห็นตัวแปรที่สร้างโดยสาขาอื่น และมีเพียงคอลัมน์จากสาขาสุดท้าย RETURN ของสาขาที่เลือกเท่านั้นที่จะดําเนินการต่อหลังจากคําสั่งเงื่อนไข ทุกสาขาต้องคืนชื่อคอลัมน์เดียวกัน และประเภทผลลัพธ์ที่สอดคล้องกันต้องเข้ากันได้ เครื่องมือค้นหาจะบังคับให้ชนิดข้อมูลที่เข้ากันได้กลายเป็นประเภทผลลัพธ์เดียวกัน คอลัมน์สาขาที่คืนค่าสามารถใช้ชื่อเดียวกับคอลัมน์ขาเข้า;ค่าสาขาจะมาแทนที่ค่าขาเข้าในผลลัพธ์แบบมีเงื่อนไข

ประโยค CASE เงื่อนไขแตกต่างจากนิพจน์ กราฟรองรับนิพจน์ที่เรียบง่าย CASE <expression> WHEN <value>แต่ไม่สามารถค้นหา CASE WHEN <predicate> ได้ สําหรับข้อมูลเพิ่มเติม ดูที่ นิพจน์เงื่อนไข

ขอบเขตตัวแปรและการควบคุมโฟลว์ขั้นสูง

ตัวแปรเชื่อมต่อข้อมูลในคําสั่งคิวรีและเปิดใช้งานการกลับรายการกราฟที่ซับซ้อน การทําความเข้าใจกฎขอบเขตขั้นสูงช่วยให้คุณเขียนคิวรีแบบหลายคําสั่งที่มีความซับซ้อน

รูปแบบการผูกตัวแปรและการกําหนดขอบเขต

-- Variables flow forward through subsequent statements 
MATCH (p:Person)                                    -- Bind p 
LET fullName = p.firstName || ' ' || p.lastName     -- Bind concatenation of p.firstName and p.lastName as fullName
FILTER fullName CONTAINS 'Smith'                    -- Filter for fullNames with “Smith” substring (p is still bound)
RETURN p.id, fullName                               -- Only return p.id and fullName (p is dropped from scope)

นําตัวแปรกลับมาใช้ใหม่สําหรับการรวมทั่วทั้งคําสั่ง

-- Multi-statement joins using variable reuse
MATCH (p:Person)-[:workAt]->(:Company)          -- Find people with jobs
MATCH (p)-[:isLocatedIn]->(:City)               -- Same p: people with both job and residence
MATCH (p)-[:knows]->(friend:Person)             -- Same p: their social connections
RETURN *

กฎการกําหนดขอบเขตและข้อจํากัดที่สําคัญ

-- ✅ Backward references work
MATCH (p:Person)
LET adult = p.birthday < 20061231  -- Can reference p from previous statement
RETURN *

-- ❌ Forward references don't work  
LET adult = p.birthday < 20061231  -- Error: p not yet defined
MATCH (p:Person)
RETURN *

-- ❌ Variables in same LET statement can't reference each other
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName,
    greeting = 'Hello, ' || name     -- Error: name not visible yet
RETURN *

-- ✅ Use separate statements for dependent variables
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName
LET greeting = 'Hello, ' || name     -- Works: name now available
RETURN *

การมองเห็นตัวแปรในคิวรีที่ซับซ้อน

-- Variables remain visible until overridden or query ends
MATCH (p:Person)                     -- p available from here
LET gender = p.gender                -- gender available from here  
MATCH (p)-[:knows]->(e:Person)       -- p still refers to original person
                                     -- e is a new variable for the friend
RETURN p.firstName AS manager, e.firstName AS friend, gender

ข้อควรระวัง

ตัวแปรในคําสั่งเดียวกันไม่สามารถอ้างอิงซึ่งกันและกัน ยกเว้นในรูปแบบกราฟ ใช้คําสั่งแยกต่างหากสําหรับการสร้างตัวแปรที่ไม่เป็นขึ้นต่อกัน

รวมแถวและองค์ประกอบเส้นทาง

GQL รองรับบริบทการรวมข้อมูลสองแบบ:

  • การรวมแนวตั้ง สรุปแถวอินพุต โดยสามารถแบ่งแยกตาม GROUP BY ตัวแปรได้ตามต้องการ
  • การรวมแนวนอน สรุปรายการกลุ่มที่ถูกจํากัดด้วยรูปแบบขอบที่มีความยาวแปรผันภายในเส้นทางที่จับคู่กันหนึ่งเส้นทาง
MATCH (person:Person)-[:workAt]->(company:Company)
LET companyId = company.id, companyName = company.name
RETURN companyId, companyName, count(*) AS employeeCount
GROUP BY companyId, companyName

MATCH (:Person)-[connections:knows]->{1,4}(:Person)
RETURN count(connections) AS pathLength

สําหรับคําค้นที่จัดกลุ่ม ตัวกรองเฉพาะกลุ่ม การรวมกลุ่ม และการกําหนดเส้นทางแบบมีเงื่อนไข ดูที่ กรองและข้อมูลกราฟรวม สําหรับกฎผลลัพธ์รวมทั้งหมด ดูที่ฟังก์ชันรวม

จัดการค่าว่างและข้อผิดพลาดในการสืบค้น

ใช้การทดสอบ null แบบชัดเจนเมื่อค่าที่ขาดหายไปต้องการการจัดการที่ชัดเจน:

MATCH (person:Person)
FILTER person.browserUsed IS NULL
RETURN person.firstName

การเปรียบเทียบกับ null จะประเมินค่าเป็น UNKNOWN, ซึ่ง a FILTER ไม่คงไว้ ใช้ coalesce() เมื่อคุณต้องการค่าสํารอง

ผลลัพธ์ของคําค้นหาประกอบด้วยข้อมูลสถานะความสําเร็จ คําเตือน เงื่อนไขที่ไม่มีข้อมูล ข้อผิดพลาดที่ผู้ใช้แก้ไขได้ และข้อผิดพลาดของระบบ ใช้รหัสสถานะสาธารณะสําหรับการไหลของการควบคุมอย่างกว้างขวาง และใช้การวินิจฉัย GQLSTATUS แบบมาตรฐานสําหรับเงื่อนไขเฉพาะ ดูผลลัพธ์และผลลัพธ์การปฏิบัติงาน รวมถึงรหัสสถานะ GQL

คําที่สงวนไว้

GQL สงวนคําสําคัญบางอย่างซึ่งคุณไม่สามารถใช้เป็นตัวระบุได้ เช่น ตัวแปร ชื่อคุณสมบัติ หรือชื่อป้ายชื่อ ดู การอ้างอิงคําสงวน GQL สําหรับรายการทั้งหมด

ถ้าคุณจําเป็นต้องใช้คําที่สงวนไว้เป็นตัวระบุ ให้หลีกเลี่ยงด้วยแบ็กทิก: `match``return`

เพื่อหลีกเลี่ยงการเลี่ยงคําที่สงวนไว้ ให้ใช้มาตรฐานการตั้งชื่อนี้:

  • สําหรับตัวระบุคําเดียว ให้ผนวกขีดล่าง: :Product_
  • สําหรับตัวระบุแบบหลายคํา ให้ใช้ camelCase หรือ PascalCase: :MyEntity, , :hasAttributetextColor

ขั้นตอนถัดไป

เนื้อหาที่เกี่ยวข้อง

  • อัปเดตล่าสุดเมื่อ