# Search (GraphQL | gRPC)

:::callout{intent="note" title="GraphQL on Weaviate Cloud"}
New Weaviate Cloud clusters are created with GraphQL disabled (the `DISABLE_GRAPHQL` environment variable is set to `true`). To query your data on Weaviate Cloud, use a [client library](../client-libraries/index.md) or the [REST Search endpoints](/weaviate/api/rest).
:::

## API

Weaviate offers [GraphQL](https://graphql.org/) and gRPC APIs for queries.

We recommend using a Weaviate [client library](../client-libraries/index.md), which abstracts away the underlying API calls and makes it easier to integrate Weaviate into your application.

However, you can query Weaviate directly using GraphQL with a POST request to the `/graphql` endpoint, or write your own `gRPC` calls based on the [gRPC](grpc.md) protobuf specification.

## All references

All references have their individual subpages. Click on one of the references below for more information.

- [Object-level queries](graphql-get.md)
- [Aggregate](graphql-aggregate.md)
- [Search operators](graphql-search-operators.md)
- [Conditional filters](graphql-filters.md)
- [Additional operators](graphql-additional-operators.md)
- [Additional properties](graphql-additional-properties.md)
- [Explore](graphql-explore.md)

## GraphQL API

### Why GraphQL?

GraphQL is a query language built on using graph data structures. It is an efficient method of data retrieval and mutation, since it mitigates the common over-fetching and under-fetching problems of other query languages.

:::callout{intent="tip" title="GraphQL is case-sensitive"}
GraphQL is case-sensitive ([reference](https://spec.graphql.org/June2018/#sec-Names)), so make sure to use the correct casing when writing your queries.
:::

### Query structure

You can POST a GraphQL query to Weaviate as follows:

```bash
curl http://localhost/v1/graphql -X POST -H 'Content-type: application/json' -d '{GraphQL query}'
```

A GraphQL JSON object is defined as:

```json
{
    "query": "{ # GRAPHQL QUERY }"
}
```

GraphQL queries follow a defined structure. Queries are structured as follows:

```graphql
{
  <Function> {
      <Collection> {
        <property>
        _<underscore-property>
      }
  }
}
```

### Limitations

GraphQL _integer_ data currently only supports `int32`, and does not support `int64`. This means that currently _integer_ data fields in Weaviate with integer values larger than `int32`, will not be returned using GraphQL queries. We are working on solving this [issue](https://github.com/weaviate/weaviate/issues/1563). As current workaround is to use a `string` instead.

### Consistency level

GraphQL (`Get`) queries are run with a tunable [consistency level](../replication-architecture/consistency.md#tunable-read-consistency).

## gRPC API

Starting with Weaviate v1.19.0, a gRPC interface is being progressively added to Weaviate.

gRPC is a high-performance, open-source universal RPC framework that is contract-based and can be used in any environment. It is based on HTTP/2 and Protocol Buffers, and is therefore very fast and efficient.

Read more about the gRPC API [here](grpc.md).

## Questions and feedback

Have a question or feedback? Here's how to reach us.

::::card-grid
:::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"}
Ask questions and connect with other developers on our **Community forum**.
:::

:::card{title="Support" href="/guides/support-overview" icon="life-buoy"}
Weaviate Cloud user or customer? Find the right channel on the **Support page**.
:::
::::

## Related pages

- [Agents](./agents-index.md)
- [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md)
- [APIs](./apis-index.md)
- [Authorization and authentication](./authorization-and-authentication-index.md)
- [Benchmarks](./benchmarks-index.md)
- [Best practices](./best-practices-index.md)
- [Client libraries](./clients-index.md)
- [Client Libraries / SDKs](./client-libraries-index.md)
- [Cloud](./cloud-index.md)
- [Cloud account management](./cloud-account-management-index.md)

# Agent Instructions

This portal answers questions programmatically. To receive a synthesized,
source-cited answer instead of crawling page by page, append the `?ask=`
query parameter to any page URL on this site:

    /guides/quickstart?ask=how+do+I+authenticate

Optional parameters:

- `&goal=<what-you-are-trying-to-do>` steers the answer toward your
  objective (e.g. `&goal=write+a+python+client`).
- `&version=<label>` scopes the answer to a mounted version when the
  portal publishes more than one.

The response is `text/markdown`: the answer followed by a `# Sources` list
of the portal pages it was grounded in. Status codes are the contract:

- `200` — the answer; `402` — the portal owner’s plan or answer credits are
  exhausted (surface this to your operator; do NOT retry); `429` — you are
  rate-limited; back off for the `Retry-After` seconds; `503` — the answer
  lane is temporarily unavailable; fall back to crawling the `.md` pages.

For the full corpus map read `llms.txt` at the site root; for the tool
surface (search + page fetch as MCP tools) see `/mcp`.