[The Graph] GraphQL API
![[The Graph] GraphQL API](https://cryptovn.io/wp-content/uploads/2020/12/The-Graph-series-7.jpg)
Hướng dẫn này giải thích API truy vấn GraphQL được sử dụng cho Giao thức đồ thị.
Truy vấn
Trong lược đồ con của bạn, bạn xác định các loại được gọi là Entities
. Đối với mỗi Entity
loại, trường entity
và entities
sẽ được tạo trên Query
loại cấp cao nhất . Lưu ý rằng query
không cần phải đưa vào đầu graphql
truy vấn khi sử dụng Biểu đồ.
Ví dụ
Truy vấn cho một Token
thực thể được xác định trong giản đồ của bạn:
{
token(id: "1") {
id
owner
}
}
Lưu ý: Khi truy vấn cho một thực thể, id
trường là bắt buộc và nó phải là một chuỗi.
Truy vấn tất cả các Token
thực thể:
{
tokens {
id
owner
}
}
Sắp xếp
Khi truy vấn một tập hợp, orderBy
tham số có thể được sử dụng để sắp xếp theo một thuộc tính cụ thể. Ngoài ra, orderDirection
có thể được sử dụng để chỉ định hướng sắp xếp, asc
tăng dần hoặc desc
giảm dần.
Thí dụ
{
tokens(orderBy: price, orderDirection: asc) {
id
owner
}
}
Phân trang
Khi truy vấn một tập hợp, first
tham số có thể được sử dụng để phân trang từ đầu tập hợp. Cần lưu ý rằng thứ tự sắp xếp mặc định là theo ID theo thứ tự chữ và số tăng dần, không phải theo thời gian tạo.
Hơn nữa, skip
tham số có thể được sử dụng để bỏ qua các thực thể và phân trang. ví dụ: first:100
hiển thị 100 thực thể đầu tiên và first:100, skip:100
hiển thị 100 thực thể tiếp theo.
Các truy vấn nên tránh sử dụng các skip
giá trị rất lớn vì chúng thường hoạt động kém. Để truy xuất một số lượng lớn các mục, tốt hơn nhiều nên trang qua các thực thể dựa trên một thuộc tính như được hiển thị trong ví dụ cuối cùng.
Thí dụ
Truy vấn 10 mã thông báo đầu tiên:
{
tokens(first: 10) {
id
owner
}
}
Để truy vấn các nhóm thực thể ở giữa một tập hợp, skip
tham số có thể được sử dụng cùng với first
tham số để bỏ qua một số thực thể được chỉ định bắt đầu từ đầu tập hợp.
Thí dụ
Truy vấn 10 Token
thực thể, bù 10 vị trí từ đầu bộ sưu tập:
{
tokens(first: 10, skip: 10) {
id
owner
}
}
Thí dụ
Nếu khách hàng cần truy xuất một số lượng lớn các thực thể, thì việc truy vấn cơ sở trên một thuộc tính và lọc theo thuộc tính đó sẽ hiệu quả hơn nhiều. Ví dụ: một khách hàng sẽ truy xuất một số lượng lớn các mã thông báo bằng cách sử dụng truy vấn này:
{
query manyTokens($lastID: String) {
tokens(first: 1000, where: { id_gt: $lastID }) {
id
owner
}
}
}
Lần đầu tiên, nó sẽ gửi các truy vấn với lastID = ""
, và cho yêu cầu tiếp theo sẽ thiết lập lastID
để các id
thuộc tính của đối tượng cuối cùng trong yêu cầu trước đó. Cách tiếp cận này sẽ hoạt động tốt hơn đáng kể so với việc sử dụng skip
các giá trị tăng dần .
Lọc
Bạn có thể sử dụng where
tham số trong các truy vấn của mình để lọc các thuộc tính khác nhau. Bạn có thể lọc theo nhiều giá trị trong where
tham số.
Thí dụ
Truy vấn thách thức với failed
kết quả:
{
challenges(where: { outcome: "failed" }) {
challenger
outcome
application {
id
}
}
}
Bạn có thể sử dụng các hậu tố như _gt
, _lte
để so sánh giá trị:
Thí dụ
{
applications(where: { deposit_gt: "10000000000" }) {
id
whitelisted
deposit
}
}
Danh sách đầy đủ các hậu tố tham số:
_not
_gt
_lt
_gte
_lte
_in
_not_in
_contains
_not_contains
_starts_with
_ends_with
_not_starts_with
_not_ends_with
Xin lưu ý rằng một số hậu tố chỉ được hỗ trợ cho các loại cụ thể. Ví dụ, Boolean
chỉ hỗ trợ _not
, _in
và _not_in
.
Truy vấn du hành thời gian
Bạn có thể truy vấn trạng thái của các thực thể của mình không chỉ cho khối mới nhất, theo mặc định, mà còn cho một khối tùy ý trong quá khứ. Khối mà tại đó truy vấn sẽ xảy ra có thể được chỉ định bằng số khối của nó hoặc hàm băm khối của nó bằng cách bao gồm một block
đối số trong các trường cấp cao nhất của truy vấn.
Kết quả của một truy vấn như vậy sẽ không thay đổi theo thời gian, tức là, truy vấn tại một khối trong quá khứ nhất định sẽ trả về cùng một kết quả bất kể nó được thực thi khi nào, ngoại trừ trường hợp bạn truy vấn tại một khối rất gần với phần đầu của Ethereum chuỗi, kết quả có thể thay đổi nếu khối đó hóa ra không nằm trên chuỗi chính và chuỗi được tổ chức lại. Khi một khối có thể được coi là cuối cùng, kết quả của truy vấn sẽ không thay đổi.
Lưu ý rằng việc triển khai hiện tại vẫn phải chịu một số hạn chế nhất định có thể vi phạm những người được bảo đảm này. Việc triển khai không phải lúc nào cũng có thể cho biết rằng một hàm băm khối nhất định hoàn toàn không nằm trên chuỗi chính hoặc kết quả của một truy vấn theo hàm băm khối cho một khối chưa thể được coi là cuối cùng có thể bị ảnh hưởng bởi việc tổ chức lại khối chạy đồng thời với truy vấn. Chúng không ảnh hưởng đến kết quả của các truy vấn theo hàm băm khối khi khối cuối cùng và được biết là nằm trên chuỗi chính. Vấn đề này giải thích chi tiết những hạn chế này là gì.
Thí dụ
{
challenges(block: { number: 8000000 }) {
challenger
outcome
application {
id
}
}
}
Truy vấn này sẽ trả về Challenge
các thực thể và các Application
thực thể được liên kết của chúng , vì chúng đã tồn tại trực tiếp sau khi xử lý số khối 8.000.000.
Thí dụ
{
challenges(block: { hash: "0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c" }) {
challenger
outcome
application {
id
}
}
}
Truy vấn này sẽ trả về Challenge
các thực thể và các Application
thực thể liên kết của chúng , vì chúng đã tồn tại trực tiếp sau khi xử lý khối với hàm băm đã cho.
Truy vấn tìm kiếm toàn văn bản
Các trường truy vấn tìm kiếm toàn văn bản cung cấp một API tìm kiếm văn bản biểu đạt có thể được thêm vào lược đồ con và tùy chỉnh. Tham khảo Xác định Trường Tìm kiếm Toàn văn bản để thêm tìm kiếm toàn văn bản vào trang con của bạn.
Các truy vấn tìm kiếm toàn văn bản có một trường bắt buộc text
, để cung cấp các cụm từ tìm kiếm. Một số toán tử toàn văn đặc biệt có sẵn để được sử dụng trong text
trường tìm kiếm này.
Toán tử tìm kiếm toàn văn bản:
Biểu tượng | Nhà điều hành | Sự miêu tả |
---|---|---|
& |
And |
Để kết hợp nhiều cụm từ tìm kiếm thành một bộ lọc cho các thực thể bao gồm tất cả các cụm từ được cung cấp |
| | Or |
Các truy vấn có nhiều cụm từ tìm kiếm được phân tách bằng toán tử hoặc sẽ trả về tất cả các thực thể có kết quả khớp với bất kỳ cụm từ được cung cấp nào |
<-> |
Follow by |
Chỉ định khoảng cách giữa hai từ. |
:* |
Prefix |
Sử dụng cụm từ tìm kiếm tiền tố để tìm các từ có tiền tố khớp (yêu cầu 2 ký tự.) |
Ví dụ
Sử dụng or
toán tử, truy vấn này sẽ lọc các thực thể blog có các biến thể của “chủ nghĩa vô chính phủ” hoặc “crumpet” trong trường văn bản đầy đủ của chúng.
{
blogSearch(text: "anarchism | crumpets") {
id
title
body
author
}
}
Các follow by
nhà điều hành chỉ định một từ một khoảng cách cụ thể ngoài trong các tài liệu toàn văn. Truy vấn sau sẽ trả về tất cả các blog có các biến thể của “phân quyền” theo sau là “triết học”
{
blogSearch(text: "decentralized <-> philosophy") {
id
title
body
author
}
}
Kết hợp các toán tử toàn văn bản để tạo các bộ lọc phức tạp hơn. Với một toán tử tìm kiếm lý do kết hợp với truy vấn theo sau bởi ví dụ này sẽ đối sánh tất cả các thực thể blog có các từ bắt đầu bằng “lou”, theo sau là “âm nhạc”.
{
blogSearch(text: "lou:* <-> music") {
id
title
body
author
}
}
Lược đồ
Lược đồ nguồn dữ liệu của bạn – nghĩa là các loại thực thể, giá trị và mối quan hệ có sẵn để truy vấn – được xác định thông qua Langauge định nghĩa giao diện GraphQL (IDL) .
GraphQL schemas thường xác định các loại gốc cho queries
, subscriptions
và mutations
. Graph chỉ hỗ trợ queries
. Query
Loại gốc cho đồ thị con của bạn được tạo tự động từ lược đồ GraphQL được bao gồm trong tệp kê khai đồ thị con của bạn.
Lưu ý: API của chúng tôi không để lộ các đột biến vì các nhà phát triển dự kiến sẽ phát hành các giao dịch trực tiếp chống lại chuỗi khối cơ bản từ các ứng dụng của họ.
Thực thể
Tất cả các loại GraphQL có @entity
chỉ thị trong lược đồ của bạn sẽ được coi là các thực thể và phải có một ID
trường.
Lưu ý: Hiện tại, tất cả các loại trong lược đồ của bạn phải có một
@entity
chỉ thị. Trong tương lai, chúng tôi sẽ coi các kiểu không có@entity
chỉ thị là các đối tượng giá trị, nhưng điều này chưa được hỗ trợ.