[The Graph] GraphQL API

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 Entityloại, trường entityvà entitiessẽ được tạo trên Queryloại cấp cao nhất . Lưu ý rằng querykhông cần phải đưa vào đầu graphqltruy vấn khi sử dụng Biểu đồ.

Ví dụ

Truy vấn cho một Tokenthự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ể, idtrường là bắt buộc và nó phải là một chuỗi.

Truy vấn tất cả các Tokenthực thể:

{
  tokens {
    id
    owner
  }
}

Sắp xếp

Khi truy vấn một tập hợp, orderBytham số có thể được sử dụng để sắp xếp theo một thuộc tính cụ thể. Ngoài ra, orderDirectioncó thể được sử dụng để chỉ định hướng sắp xếp, asctăng dần hoặc descgiả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, firsttham 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, skiptham số có thể được sử dụng để bỏ qua các thực thể và phân trang. ví dụ: first:100hiển thị 100 thực thể đầu tiên và first:100, skip:100hiển thị 100 thực thể tiếp theo.

Các truy vấn nên tránh sử dụng các skipgiá 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, skiptham số có thể được sử dụng cùng với firsttham 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 Tokenthự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 idthuộ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 skipcác giá trị tăng dần .

Lọc

Bạn có thể sử dụng wheretham 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 wheretham số.

Thí dụ

Truy vấn thách thức với failedkế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ụ, Booleanchỉ hỗ trợ _not, _invà _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ề Challengecác thực thể và các Applicationthự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ề Challengecác thực thể và các Applicationthự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 texttrường tìm kiếm này.

Toán tử tìm kiếm toàn văn bản:

Ví dụ

Sử dụng ortoá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 bynhà đ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, subscriptionsvà mutations. Graph chỉ hỗ trợ queries. QueryLoạ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ó @entitychỉ thị trong lược đồ của bạn sẽ được coi là các thực thể và phải có một IDtrườ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 @entitychỉ thị. Trong tương lai, chúng tôi sẽ coi các kiểu không có @entitychỉ thị là các đối tượng giá trị, nhưng điều này chưa được hỗ trợ.

Jade Vo