# SubgraphService

Defined in: [packages/synapse-sdk/src/subgraph/service.ts:170](https://github.com/FilOzone/synapse-sdk/blob/6cf8b3ed2dd3ae76ed05cb86995d711a08a298a6/packages/synapse-sdk/src/subgraph/service.ts#L170)

Defines the contract for a service that can retrieve provider information from a data source,
typically a Synapse-compatible subgraph.

This interface allows for custom implementations to be provided in place of the default
SubgraphService. Any service that implements this interface can be used with the
Synapse SDK by passing it via the `subgraphService` option when creating a Synapse instance.

This enables integration with alternative data sources or custom implementations
while maintaining compatibility with the SDK's retrieval system.

## Implements

- [`SubgraphRetrievalService`](/reference/filoz/synapse-sdk/synapse/interfaces/subgraphretrievalservice/)

## Constructors

### Constructor

> **new SubgraphService**(`subgraphConfig`): `SubgraphService`

Defined in: [packages/synapse-sdk/src/subgraph/service.ts:174](https://github.com/FilOzone/synapse-sdk/blob/6cf8b3ed2dd3ae76ed05cb86995d711a08a298a6/packages/synapse-sdk/src/subgraph/service.ts#L174)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `subgraphConfig` | [`SubgraphConfig`](/reference/filoz/synapse-sdk/synapse/interfaces/subgraphconfig/) |

#### Returns

`SubgraphService`

## Methods

### getApprovedProvidersForPieceCID()

> **getApprovedProvidersForPieceCID**(`pieceCid`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`ProviderInfo`](/reference/filoz/synapse-sdk/synapse/interfaces/providerinfo/)[]\>

Defined in: [packages/synapse-sdk/src/subgraph/service.ts:476](https://github.com/FilOzone/synapse-sdk/blob/6cf8b3ed2dd3ae76ed05cb86995d711a08a298a6/packages/synapse-sdk/src/subgraph/service.ts#L476)

Queries the subgraph to find approved service providers that have a specific piece (PieceCID).

It sends a GraphQL query to the configured endpoint and parses the response to extract
a list of providers, including their addresses and retrieval URLs.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `pieceCid` | `PieceLink` | The piece commitment (PieceCID) to search for. |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`ProviderInfo`](/reference/filoz/synapse-sdk/synapse/interfaces/providerinfo/)[]\>

A promise that resolves to an array of `ProviderInfo` objects.
         Returns an empty array if no providers are found or if an error occurs during the fetch.

#### Implementation of

[`SubgraphRetrievalService`](/reference/filoz/synapse-sdk/synapse/interfaces/subgraphretrievalservice/).[`getApprovedProvidersForPieceCID`](/reference/filoz/synapse-sdk/synapse/interfaces/subgraphretrievalservice/#getapprovedprovidersforpiececid)

***

### getProviderByAddress()

> **getProviderByAddress**(`address`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`ProviderInfo`](/reference/filoz/synapse-sdk/synapse/interfaces/providerinfo/) \| `null`\>

Defined in: [packages/synapse-sdk/src/subgraph/service.ts:521](https://github.com/FilOzone/synapse-sdk/blob/6cf8b3ed2dd3ae76ed05cb86995d711a08a298a6/packages/synapse-sdk/src/subgraph/service.ts#L521)

Queries the subgraph to find a specific approved service provider by their address.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `address` | `` `0x${string}` `` | The wallet address of the provider to search for. |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`ProviderInfo`](/reference/filoz/synapse-sdk/synapse/interfaces/providerinfo/) \| `null`\>

A promise that resolves to an `ProviderInfo` object if the provider is found, or `null` otherwise.

#### Implementation of

[`SubgraphRetrievalService`](/reference/filoz/synapse-sdk/synapse/interfaces/subgraphretrievalservice/).[`getProviderByAddress`](/reference/filoz/synapse-sdk/synapse/interfaces/subgraphretrievalservice/#getproviderbyaddress)

***

### queryDataSets()

> **queryDataSets**(`options`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`DetailedSubgraphDataSetInfo`](/reference/filoz/synapse-sdk/subgraph/interfaces/detailedsubgraphdatasetinfo/)[]\>

Defined in: [packages/synapse-sdk/src/subgraph/service.ts:601](https://github.com/FilOzone/synapse-sdk/blob/6cf8b3ed2dd3ae76ed05cb86995d711a08a298a6/packages/synapse-sdk/src/subgraph/service.ts#L601)

Generic method to query data sets with flexible where clauses

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`QueryOptions`](/reference/filoz/synapse-sdk/subgraph/interfaces/queryoptions/) | Query options including where clause, pagination, and ordering |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`DetailedSubgraphDataSetInfo`](/reference/filoz/synapse-sdk/subgraph/interfaces/detailedsubgraphdatasetinfo/)[]\>

A promise that resolves to an array of `DetailedSubgraphDataSetInfo` objects

#### Example

```typescript
// Get active data sets
const activeDataSets = await service.queryDataSets({
  where: { isActive: true },
  first: 50,
  orderBy: "createdAt",
  orderDirection: "desc"
});

// Get data sets by owner with minimum data size
const largeDataSets = await service.queryDataSets({
  where: {
    owner: "0x123...",
    totalDataSize_gte: "1000000000"
  }
});
```

***

### queryFaultRecords()

> **queryFaultRecords**(`options`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`FaultRecord`](/reference/filoz/synapse-sdk/subgraph/interfaces/faultrecord/)[]\>

Defined in: [packages/synapse-sdk/src/subgraph/service.ts:737](https://github.com/FilOzone/synapse-sdk/blob/6cf8b3ed2dd3ae76ed05cb86995d711a08a298a6/packages/synapse-sdk/src/subgraph/service.ts#L737)

Generic method to query fault records with flexible where clauses

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`QueryOptions`](/reference/filoz/synapse-sdk/subgraph/interfaces/queryoptions/) | Query options including where clause, pagination, and ordering |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`FaultRecord`](/reference/filoz/synapse-sdk/subgraph/interfaces/faultrecord/)[]\>

A promise that resolves to an array of `FaultRecord` objects

#### Example

```typescript
// Get recent fault records
const recentFaults = await service.queryFaultRecords({
  where: { createdAt_gte: "1640995200" },
  first: 20,
  orderBy: "createdAt",
  orderDirection: "desc"
});

// Get fault records for specific data set
const dataSetFaults = await service.queryFaultRecords({
  where: { dataSetId: "123" }
});
```

***

### queryPieces()

> **queryPieces**(`options`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`PieceInfo`](/reference/filoz/synapse-sdk/subgraph/interfaces/pieceinfo/)[]\>

Defined in: [packages/synapse-sdk/src/subgraph/service.ts:677](https://github.com/FilOzone/synapse-sdk/blob/6cf8b3ed2dd3ae76ed05cb86995d711a08a298a6/packages/synapse-sdk/src/subgraph/service.ts#L677)

Generic method to query pieces with flexible where clauses

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`QueryOptions`](/reference/filoz/synapse-sdk/subgraph/interfaces/queryoptions/) | Query options including where clause, pagination, and ordering |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`PieceInfo`](/reference/filoz/synapse-sdk/subgraph/interfaces/pieceinfo/)[]\>

A promise that resolves to an array of `PieceInfo` objects

#### Example

```typescript
// Get pieces by data set
const dataSetPieces = await service.queryPieces({
  where: { dataSet: "0x123..." },
  first: 100,
  orderBy: "createdAt"
});

// Get non-removed pieces with minimum size
const largePieces = await service.queryPieces({
  where: {
    removed: false,
    rawSize_gte: "1000000"
  }
});
```

***

### queryProviders()

> **queryProviders**(`options`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`ProviderInfo`](/reference/filoz/synapse-sdk/synapse/interfaces/providerinfo/)[]\>

Defined in: [packages/synapse-sdk/src/subgraph/service.ts:559](https://github.com/FilOzone/synapse-sdk/blob/6cf8b3ed2dd3ae76ed05cb86995d711a08a298a6/packages/synapse-sdk/src/subgraph/service.ts#L559)

Generic method to query providers with flexible where clauses

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`QueryOptions`](/reference/filoz/synapse-sdk/subgraph/interfaces/queryoptions/) | Query options including where clause, pagination, and ordering |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`ProviderInfo`](/reference/filoz/synapse-sdk/synapse/interfaces/providerinfo/)[]\>

A promise that resolves to an array of `ProviderInfo` objects

#### Example

```typescript
// Get providers with specific status
const approvedProviders = await service.queryProviders({
  where: { status: "APPROVED" },
  first: 10,
  orderBy: "approvedAt",
  orderDirection: "desc"
});

// Get providers with minimum data sets
const activeProviders = await service.queryProviders({
  where: { totalDataSets_gte: "5" },
  first: 20
});
```