postgraphile-plugin-connection-filter

This plugin adds a filter argument to Connection types in PostGraphile v4.

Note: This plugin targets the alpha release of PostGraphile v4. Because of possible API changes, releases of this plugin are pinned to specific alpha versions of PostGraphile. See the Compatibility table below for details.

Warning: This plugin exposes a large number of operators (including some that can perform expensive pattern matching) by default. Before enabling this plugin in production, you should consider the performance and security implications. Use of the connectionFilterAllowedOperators option to limit the operators exposed through GraphQL is strongly encouraged.

Compatibility

Getting Started

CLI

postgraphile --append-plugins `pwd`/path/to/this/plugin/index.js

Library

const express = require("express");
const { postgraphile } = require("postgraphile");
const PostGraphileConnectionFilterPlugin = require("postgraphile-plugin-connection-filter");

const app = express();

app.use(
  postgraphile(pgConfig, schema, {
    graphiql: true,
    appendPlugins: [PostGraphileConnectionFilterPlugin],
  })
);

app.listen(5000);

Operators

The following filter operators are exposed by default:

Logical Operators

Comparison Operators

Examples

Null values

query {
  allPosts(filter: { body: { null: true } }) {
    ...
  }
}

Non-null values

query {
  allPosts(filter: { body: { null: false } }) {
    ...
  }
}

Comparison operator with scalar input

query {
  allPosts(filter: { createdAt: { greaterThan: "2016-01-01" } }) {
    ...
  }
}

Comparison operator with array input

query {
  allPosts(filter: { authorId: { in: [1, 2] } }) {
    ...
  }
}

Multiple comparison operators

query {
  allPosts(filter: {
    body: { null: false },
    createdAt: { greaterThan: "2016-01-01" }
  }) {
    ...
  }
}

Note: Objects with multiple keys are interpreted with an implicit AND between the conditions.

Logical operator

query {
  allPosts(filter: {
    or: [
      { authorId: { equalTo: 6 } },
      { createdAt: { greaterThan: "2016-01-01" } }
    ]
  }) {
    ...
  }
}

Nested logic

query {
  allPosts(filter: {
    not: {
      or: [
        { authorId: { equalTo: 6 } },
        { createdAt: { greaterThan: "2016-01-01" } }
      ]
    }
  }) {
    ...
  }
}

For additional examples, see the tests.

Plugin Options

When using PostGraphile as a library, the following plugin options can be passed via graphileBuildOptions (called graphqlBuildOptions in PostGraphile 4.0.0-alpha2.20 and earlier):

connectionFilterAllowedOperators

Restrict filtering to specific operators

postgraphile(pgConfig, schema, {
  graphileBuildOptions: {
    connectionFilterAllowedOperators: [
      "null",
      "equalTo",
      "notEqualTo",
      "distinctFrom",
      "notDistinctFrom",
      "lessThan",
      "lessThanOrEqualTo",
      "greaterThan",
      "greaterThanOrEqualTo",
      "in",
      "notIn",
    ],
  },
})

For a full list of the available operators, see the Comparison Operators table above.

connectionFilterAllowedFieldTypes

Restrict filtering to specific field types

postgraphile(pgConfig, schema, {
  graphileBuildOptions: {
    connectionFilterAllowedFieldTypes: ["String", "Int"],
  },
})

The available field types will depend on your database schema.

connectionFilterOperatorNames

Use alternative names (e.g. eq, ne) for operators

postgraphile(pgConfig, schema, {
  graphileBuildOptions: {
    connectionFilterOperatorNames: {
      equalTo: "eq",
      notEqualTo: "ne",
    },
  },
})

Note: The connectionFilterUsesShortNames option was removed in v1.0.0-alpha.6. To restore the old functionality, you can use this:

postgraphile(pgConfig, schema, {
  graphileBuildOptions: {
    connectionFilterOperatorNames: {
      equalTo: "eq",
      notEqualTo: "ne",
      lessThan: "lt",
      lessThanOrEqualTo: "lte",
      greaterThan: "gt",
      greaterThanOrEqualTo: "gte",
      in: "in",
      notIn: "nin",
      contains: "cont",
      notContains: "ncont",
      containsInsensitive: "conti",
      notContainsInsensitive: "nconti",
      startsWith: "starts",
      notStartsWith: "nstarts",
      startsWithInsensitive: "startsi",
      notStartsWithInsensitive: "nstartsi",
      endsWith: "ends",
      notEndsWith: "nends",
      endsWithInsensitive: "endsi",
      notEndsWithInsensitive: "nendsi",
      like: "like",
      notLike: "nlike",
      likeInsensitive: "ilike",
      notLikeInsensitive: "nilike",
    },
  },
})

Development

To establish a test environment, create an empty Postgres database (e.g. graphile_build_test) and set a TEST_DATABASE_URL environment variable with your connection string (e.g. postgres://localhost:5432/graphile_build_test). Ensure that psql is installed locally and then run:

npm install
npm test