Docs
⌘ K

12 मिनट

ग्राफक्यूएल एपीआई

The Graph में उपयोग किए जाने वाले GraphQL Query API के बारे में जानें।

GraphQL क्या है?

GraphQL⁠ एक API के लिए क्वेरी भाषा है और मौजूदा डेटा के साथ उन क्वेरियों को निष्पादित करने के लिए एक रनटाइम है। The Graph, GraphQL का उपयोग करके Subgraphs से क्वेरी करता है।

To समझने के लिए कि GraphQL बड़ी भूमिका कैसे निभाता है, developing और creating a Subgraph की समीक्षा करें।

GraphQL के साथ क्वेरीज़

आपकी Subgraph schema में Entities नामक प्रकारों को परिभाषित किया जाता है। प्रत्येक Entity प्रकार के लिए, शीर्ष-स्तरीय Query प्रकार पर entity और entities फ़ील्ड जेनरेट की जाएंगी।

ध्यान दें: ‘queries’ को The Graph का उपयोग करते समय ‘graphql’ क्वेरी के शीर्ष पर शामिल करने की आवश्यकता नहीं है।

उदाहरण

एकल ‘Token’ एंटिटी के लिए क्वेरी करें जो आपके स्कीमा में परिभाषित है

{  token(id: "1") {    id    owner  }}

नोट: जब किसी एकल entities के लिए क्वेरी की जा रही हो, तो ‘id’ फ़ील्ड आवश्यक है, और इसे एक स्ट्रिंग के रूप में लिखा जाना चाहिए।

सभी ‘Token’ entities को क्वेरी करें:

{  tokens {    id    owner  }}

Her translation means sorting out

जब आप एक संग्रह के लिए क्वेरी कर रहे हों, तो आप:

  • ‘orderBy’ पैरामीटर का उपयोग किसी विशिष्ट गुण द्वारा सॉर्ट करने के लिए करें।
  • ‘orderDirection’ का उपयोग सॉर्ट दिशा निर्दिष्ट करने के लिए करें, ‘asc’ के लिए आरोही या ‘desc’ के लिए अवरोही।

उदाहरण

{  tokens(orderBy: price, orderDirection: asc) {    id    owner  }}

नेस्टेड इकाई छँटाई के लिए उदाहरण

Graph Node ‘v0.30.0’⁠ के अनुसार, entities को nested entities के आधार पर क्रमबद्ध किया जा सकता है।

निम्नलिखित उदाहरण में टोकन उनके मालिक के नाम के अनुसार क्रमबद्ध किए गए हैं:

{  tokens(orderBy: owner__name, orderDirection: asc) {    id    owner {      name    }  }}

वर्तमान में, आप ‘@entity’ और ‘@derivedFrom’ फ़ील्ड्स पर एक-स्तरीय गहरे ‘String’ या ‘ID’ प्रकारों द्वारा क्रमबद्ध कर सकते हैं। अफसोस,इंटरफेस द्वारा एक-स्तरीय गहरे entities पर क्रमबद्ध करना⁠, ऐसे फ़ील्ड्स द्वारा क्रमबद्ध करना जो एरेज़ और नेस्टेड entities हैं, अभी तक समर्थित नहीं है।

पृष्ठ पर अंक लगाना

जब एक संग्रह के लिए क्वेरी की जाती है, तो यह सबसे अच्छा होता है:

  • संग्रह की शुरुआत से पेजिनेट करने के लिए first पैरामीटर का उपयोग करें।
    • डिफ़ॉल्ट सॉर्ट आदेश ID के अनुसार आरोही अल्फ़ान्यूमेरिक क्रम में होता है, न कि निर्माण समय के अनुसार।
  • skip पैरामीटर का उपयोग entities को स्किप करने और पेजिनेट करने के लिए करें। instancesके लिए, first:100 पहले 100 entities दिखाता है और first:100, skip:100 अगले 100 entities दिखाता है।
  • skip मानों का उपयोग queries में करने से बचें क्योंकि ये सामान्यतः खराब प्रदर्शन करते हैं। एक बड़ी संख्या में आइटम प्राप्त करने के लिए, पिछले उदाहरण में दिखाए गए अनुसार किसी गुण के आधार पर entities के माध्यम से पेज करना सबसे अच्छा होता है।

उदाहरण जो first का उपयोग करता है

पहले 10 टोकन पूछें:

{  tokens(first: 10) {    id    owner  }}

संग्रह के मध्य में स्थित entities के समूहों के लिए queries करने के लिए, skip पैरामीटर को first पैरामीटर के साथ उपयोग किया जा सकता है, ताकि संग्रह की शुरुआत से निर्धारित संख्या में entities को छोड़ दिया जा सके।

first और skip का उपयोग करते हुए उदाहरण

कलेक्शन की शुरुआत से 10 स्थानों के बाद 10 Token entities को queries करें।

{  tokens(first: 10, skip: 10) {    id    owner  }}

उदाहरण ‘first’ और ‘id_ge’ का उपयोग करते हुए।

यदि एक क्लाइंट को बड़ी संख्या में एंटिटीज़ पुनर्प्राप्त करने की आवश्यकता है, तो एट्रिब्यूट पर आधारित क्वेरी बनाना और उस एट्रिब्यूट द्वारा फ़िल्टर करना अधिक प्रभावशाली है। उदाहरण के लिए, एक क्लाइंट इस क्वेरी का उपयोग करके बड़ी संख्या में टोकन पुनर्प्राप्त कर सकता है:

query manyTokens($lastID: String) {  tokens(first: 1000, where: { id_gt: $lastID }) {    id    owner  }}

पहली बार, यह queries को lastID = "", के साथ भेजेगा, और subsequent requests के लिए यह lastID को पिछले अनुरोध में आखिरी entity के id attribute के रूप में सेट करेगा। यह तरीका increasing ‘skip’ मानों का उपयोग करने की तुलना में काफी बेहतर प्रदर्शन करेगा।

छनन

  • आप अपनी क्वेरी में विभिन्न गुणों को फ़िल्टर करने के लिए ‘where’ पैरामीटर का उपयोग कर सकते हैं।
  • आप ‘where’ पैरामीटर के भीतर कई मानों पर फ़िल्टर कर सकते हैं।

उदाहरण ‘where’ का उपयोग करते हुए

‘failed’ परिणाम वाली क्वेरी चुनौतियाँ:

{  challenges(where: { outcome: "failed" }) {    challenger    outcome    application {      id    }  }}

आप मूल्य तुलना के लिए ‘_gt’ , ‘_lte’ जैसे प्रत्ययों का उपयोग कर सकते हैं।

श्रेणी फ़िल्टरिंग के लिए उदाहरण

{  applications(where: { deposit_gt: "10000000000" }) {    id    whitelisted    deposit  }}

ब्लॉक फ़िल्टरिंग के लिए उदाहरण

आप उन इकाइयों entities को भी फ़िल्टर कर सकते हैं जिन्हें किसी निर्दिष्ट ब्लॉक में या उसके बाद अपडेट किया गया था, ‘_change_block(number_gte: Int)’ के साथ।

यह उपयोगी हो सकता है यदि आप केवल उन entities को लाना चाहते हैं जो बदल गई हैं, उदाहरण के लिए, पिछली बार जब आपने पोल किया था तब से। या वैकल्पिक रूप से, यह जांचने या डिबग करने के लिए उपयोगी हो सकता है कि आपकी Subgraph में entities कैसे बदल रही हैं (यदि इसे एक ब्लॉक फ़िल्टर के साथ जोड़ा जाए, तो आप केवल उन्हीं entities को अलग कर सकते हैं जो एक विशिष्ट ब्लॉक में बदली हैं)।

{  applications(where: { _change_block: { number_gte: 100 } }) {    id    whitelisted    deposit  }}

नेस्टेड इकाई फ़िल्टरिंग के लिए उदाहरण

नेस्टेड इकाइयों के आधार पर फ़िल्टरिंग उन फ़ील्ड्स में संभव है जिनके अंत में ’_’ प्रत्यय होता है।

यह उपयोगी हो सकता है यदि आप केवल उन संस्थाओं को लाना चाहते हैं जिनके चाइल्ड-स्तरीय निकाय प्रदान की गई शर्तों को पूरा करते हैं।

{  challenges(where: { application_: { id: 1 } }) {    challenger    outcome    application {      id    }  }}

लॉजिकल ऑपरेटर्स

ग्राफ-नोड ‘v0.30.0’⁠ से, आप एक ही ‘where’ आर्गुमेंट में कई पैरामीटर्स को समूहित कर सकते हैं और ‘and’ या ‘or’ ऑपरेटर्स का उपयोग करके एक से अधिक मानदंडों के आधार पर परिणामों को फ़िल्टर कर सकते हैं।

AND ऑपरेटर

निम्नलिखित उदाहरण उन चुनौतियों को फ़िल्टर करता है जिनका outcome`` succeeded है और जिनका number 100 या उससे अधिक है।

{  challenges(where: { and: [{ number_gte: 100 }, { outcome: "succeeded" }] }) {    challenger    outcome    application {      id    }  }}

सिंटैक्टिक शुगर: आप उपरोक्त को queriesसरल बना सकते हैं and ऑपरेटर को हटाकर और उप-वाक्यांश को कॉमा से अलग करके पास करके।

{  challenges(where: { number_gte: 100, outcome: "succeeded" }) {    challenger    outcome    application {      id    }  }}
OR ऑपरेटर।

निम्नलिखित उदाहरण उन चुनौतियों को फ़िल्टर करता है जिनका outcome succeeded है या जिनका number 100 या उससे अधिक है।

{  challenges(where: { or: [{ number_gte: 100 }, { outcome: "succeeded" }] }) {    challenger    outcome    application {      id    }  }}

नोट: queries बनाते समय, or ऑपरेटर के उपयोग से होने वाले प्रदर्शन प्रभावों पर विचार करना महत्वपूर्ण है। हालांकि or खोज परिणामों को व्यापक बनाने के लिए एक उपयोगी उपकरण हो सकता है, लेकिन इसके कुछ महत्वपूर्ण लागतें भी होती हैं। or के साथ मुख्य समस्या यह है कि यह queries को धीमा कर सकता है। इसका कारण यह है कि or के उपयोग से डेटाबेस को कई इंडेक्स स्कैन करने पड़ते हैं, जो एक समय-सापेक्ष प्रक्रिया हो सकती है। इन समस्याओं से बचने के लिए, यह अनुशंसा की जाती है कि डेवलपर्स or के बजाय and ऑपरेटर का उपयोग करें जब भी संभव हो। यह अधिक सटीक फ़िल्टरिंग की अनुमति देता है और तेज़, अधिक सटीक queries प्रदान कर सकता है।

सभी फ़िल्टर

पैरामीटर प्रत्यय की पूरी सूची:

__not_gt_lt_gte_lte_in_not_in_contains_contains_nocase_not_contains_not_contains_nocase_starts_with_starts_with_nocase_ends_with_ends_with_nocase_not_starts_with_not_starts_with_nocase_not_ends_with_not_ends_with_nocase

कुछ प्रत्यय केवल विशिष्ट प्रकारों के लिए समर्थित होते हैं। उदाहरण के लिए, Boolean केवल _not, _in, और _not_in का समर्थन करता है, लेकिन _ केवल ऑब्जेक्ट और इंटरफेस प्रकारों के लिए उपलब्ध है।

इसके अलावा, where आर्ग्यूमेंट के हिस्से के रूप में निम्नलिखित वैश्विक फ़िल्टर उपलब्ध हैं:

_change_block(number_gte: Int)

समय-यात्रा क्वेरी

आप न केवल नवीनतम ब्लॉक के लिए, जो डिफ़ॉल्ट होता है, बल्कि अतीत के किसी भी मनमाने ब्लॉक के लिए भी अपनी entities की स्थिति को queries कर सकते हैं। जिस ब्लॉक पर queries होनी चाहिए, उसे या तो उसके ब्लॉक नंबर या उसके ब्लॉक हैश द्वारा निर्दिष्ट किया जा सकता है, इसके लिए queries के शीर्ष स्तर के फ़ील्ड्स में block आर्ग्यूमेंट शामिल किया जाता है।

ऐसे queries का परिणाम समय के साथ नहीं बदलेगा, यानी किसी निश्चित पिछले ब्लॉक परqueries करने से हमेशा वही परिणाम मिलेगा, चाहे इसे कभी भी निष्पादित किया जाए। इसका एकमात्र अपवाद यह है कि यदि आप किसी ऐसे ब्लॉक पर queries करते हैं जो chain के हेड के बहुत करीब है, तो परिणाम बदल सकता है यदि वह ब्लॉक मुख्य chain पर not होता है और chain का पुनर्गठन हो जाता है। एक बार जब किसी ब्लॉक को अंतिम (final) माना जा सकता है, तो queries का परिणाम नहीं बदलेगा।

Note: The current implementation is still subject to certain limitations that might violate these guarantees. The implementation can not always tell that a given block hash is not on the main chain at all, or if a query result by a block hash for a block that is not yet considered final could be influenced by a block reorganization running concurrently with the query. They do not affect the results of queries by block hash when the block is final and known to be on the main chain. This issue⁠ explains what these limitations are in detail.

उदाहरण

{  challenges(block: { number: 8000000 }) {    challenger    outcome    application {      id    }  }}

यह queries Challenge entities और उनके संबद्ध Application entities को लौटाएगी, जैसा कि वे ब्लॉक संख्या 8,000,000 के प्रोसेस होने के ठीक बाद मौजूद थे।

उदाहरण

{  challenges(block: { hash: "0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c" }) {    challenger    outcome    application {      id    }  }}

यह queries Challenge entities और उनसे संबंधित Application entities को वापस करेगी, जैसा कि वे दिए गए हैश वाले ब्लॉक को प्रोसेस करने के तुरंत बाद मौजूद थीं।

पूर्ण पाठ खोज प्रश्न

Fulltext search query fields एक अभिव्यक्तिपूर्ण टेक्स्ट खोज API प्रदान करते हैं जिसे Subgraph schema में जोड़ा जा सकता है और अनुकूलित किया जा सकता है। Fulltext search को अपने Subgraph में जोड़ने के लिए Defining Fulltext Search Fields देखें।

फ़ुलटेक्स्ट सर्च क्वेरीज़ में एक आवश्यक फ़ील्ड होता है, ’ text ’, जिसमें सर्च शब्द प्रदान किए जाते हैं। इस ’ text ’ सर्च फ़ील्ड में उपयोग करने के लिए कई विशेष फ़ुलटेक्स्ट ऑपरेटर उपलब्ध हैं।

पूर्ण पाठ खोज ऑपरेटर:

प्रतीकऑपरेटरDescription
&Andसभी प्रदान किए गए शब्दों को शामिल करने वाली संस्थाओं के लिए एक से अधिक खोज शब्दों को फ़िल्टर में संयोजित करने के लिए
|’ Or’या ऑपरेटर द्वारा अलग किए गए एकाधिक खोज शब्दों वाली क्वेरी सभी संस्थाओं को प्रदान की गई शर्तों में से किसी से मेल के साथ वापस कर देगी
<->’ द्वारा अनुसरण करें ‘दो शब्दों के बीच की दूरी निर्दिष्ट करें।
:*’ उपसर्ग ‘उन शब्दों को खोजने के लिए उपसर्ग खोज शब्द का उपयोग करें जिनके उपसर्ग मेल खाते हैं (2 वर्ण आवश्यक हैं।)

उदाहरण

’ or ‘ऑपरेटर का उपयोग करके, यह क्वेरी उन ब्लॉग एंटिटीज़ को फ़िल्टर करेगी जिनके पूर्ण-पाठ (fulltext) फ़ील्ड में “anarchism” या “crumpet” में से किसी एक के विभिन्न रूप शामिल हैं।

{  blogSearch(text: "anarchism | crumpets") {    id    title    body    author  }}

’ follow by ’ ऑपरेटर पूर्ण-पाठ दस्तावेज़ों में विशिष्ट दूरी पर स्थित शब्दों को निर्दिष्ट करता है। निम्नलिखित क्वेरी उन सभी ब्लॉगों को लौटाएगी जिनमें “विकेंद्रीकृत” के विभिन्न रूप “philosophy” के बाद आते हैं।

{  blogSearch(text: "decentralized <-> philosophy") {    id    title    body    author  }}

अधिक जटिल फिल्टर बनाने के लिए फुलटेक्स्ट ऑपरेटरों को मिलाएं। इस उदाहरण क्वेरी के अनुसरण के साथ एक बहाना खोज ऑपरेटर संयुक्त रूप से सभी ब्लॉग संस्थाओं को उन शब्दों से मिलाएगा जो “लू” से शुरू होते हैं और उसके बाद “संगीत”।

{  blogSearch(text: "lou:* <-> music") {    id    title    body    author  }}

मान्यकरण

Graph Node अपने द्वारा प्राप्त GraphQL क्वेरी की स्पेसिफिकेशन-आधारित(https://spec.graphql.org/October2021/#sec-Validation⁠) वैलिडेशन करता है, जो graphql-tools-rs(https://github.com/dotansimha/graphql-tools-rs#validation-rules⁠) पर आधारित है, जो graphql-js संदर्भ कार्यान्वयन(https://github.com/graphql/graphql-js/tree/main/src/validation⁠) पर आधारित है। क्वेरी जो वैलिडेशन नियम में विफल होती हैं, वे एक मानक त्रुटि के साथ विफल होती हैं - अधिक जानने के लिए GraphQL स्पेसिफिकेशन(https://spec.graphql.org/October2021/#sec-Validation⁠) पर जाएं।

योजना

आपके डेटा स्रोतों का स्कीमा, अर्थात् उपलब्ध प्रश्न करने के लिए संस्थाओं की प्रकार, मान और उनके बीच के संबंध, GraphQL Interface Definition Language (IDL)(https://facebook.github.io/graphql/draft/#sec-Type-System⁠) के माध्यम से परिभाषित किए गए हैं।

GraphQL स्कीमाएँ आमतौर पर queries, subscriptions और mutations के लिए रूट टाइप्स को परिभाषित करती हैं। The Graph केवल queries को सपोर्ट करता है। आपके Subgraph के लिए रूट Query टाइप अपने आप उत्पन्न हो जाता है, जो कि आपके Subgraph manifest में शामिल GraphQL स्कीमा से आता है।

ध्यान दें: हमारा एपीआई म्यूटेशन को उजागर नहीं करता है क्योंकि डेवलपर्स से उम्मीद की जाती है कि वे अपने एप्लिकेशन से अंतर्निहित ब्लॉकचेन के खिलाफ सीधे लेन-देन(transaction) जारी करेंगे।

इकाइयां

आपके स्कीमा में जिन भी GraphQL प्रकारों में @entity निर्देश होते हैं, उन्हें संस्थाएँ (entities) माना जाएगा और उनमें एक ID फ़ील्ड होना चाहिए।

नोट: वर्तमान में, आपकी स्कीमा में सभी प्रकारों में @entity निर्देश होना चाहिए। भविष्य में, हम उन प्रकारों को मूल्य वस्तुएं मानेंगे जिनमें @entity निर्देश नहीं होगा, लेकिन यह अभी तक समर्थित नहीं है।

सबग्राफ मेटाडेटा

सभी Subgraph में एक स्वचालित रूप से उत्पन्न _Meta_ ऑब्जेक्ट होता है, जो Subgraph मेटाडाटा तक पहुंच प्रदान करता है। इसे निम्नलिखित तरीके से क्वेरी किया जा सकता है:

{  _meta(block: { number: 123987 }) {    block {      number      hash      timestamp    }    deployment    hasIndexingErrors  }}

यदि कोई ब्लॉक प्रदान किया जाता है, तो मेटाडेटा उस ब्लॉक के अनुसार होगा, यदि नहीं, तो नवीनतम इंडेक्स किया गया ब्लॉक उपयोग किया जाएगा। यदि प्रदान किया जाता है, तो ब्लॉक को Subgraph के प्रारंभिक ब्लॉक के बाद और सबसे हाल ही में इंडेक्स किए गए ब्लॉक के बराबर या उससे कम होना चाहिए।

deployment एक विशिष्ट ID है, जो subgraph.yaml फ़ाइल के IPFS CID के अनुरूप है।

block नवीनतम ब्लॉक के बारे में जानकारी प्रदान करता है (किसी भी ब्लॉक सीमाओं को ध्यान में रखते हुए जो कि _meta में पास की जाती हैं):

  • हैश: ब्लॉक का हैश
  • नंबर: ब्लॉक नंबर
  • टाइमस्टैम्प: यदि उपलब्ध हो, तो ब्लॉक का टाइमस्टैम्प (यह वर्तमान में केवल EVM नेटवर्क को इंडेक्स करने वाले Subgraphs के लिए उपलब्ध है)

hasIndexingErrors एक boolean है जो यह पहचानता है कि Subgraph को किसी पिछले block पर Indexing errors का सामना करना पड़ा था।