GraphQL

The GraphQL API is implemented with Ariadne. See https://ariadnegraphql.org/docs/intro for documentation.

The backend.graphql package is laid out as follows:

graphql/
├── __init__.py          # Exports the final `schema`.
├── enums.py             # Contains the GraphQL enum resolvers.
├── mutation.py          # Contains the base `mutation` type.
├── query.py             # Contains the base `query` type.
├── scalars.py           # Contains the GraphQL scalar resolvers.
├── schema.graphql       # The complete and raw GraphQL schema.
├── util.py              # Utility functions for GraphQL resolvers.
└── types/               # The resolvers for each GraphQL type.

Note

GraphQL is notorious for having the N+1 problem baked in. However, this doesn’t impact SQLite the same way it impacts other RDBMSes.

For more information, see https://sqlite.org/np1queryprob.html.

Schema

For quick reference, the raw GraphQL schema is included below:

scalar PosixTime

type Query {
  "Fetch the currently authenticated user."
  user: User!

  "Fetch the current application config."
  config: Config!

  "Search artists."
  artists(
    """
    A search string. We split this up into individual punctuation-less
    token and return artists whose name contain each token.
    """
    search: String
    "Which page of artists to return."
    page: Int
    """
    The number of artists per-page. Leave null to return all artists (and
    ignore `page`).
    """
    perPage: Int
  ): Artists!

  "Fetch an artist by ID."
  artist(id: Int!): Artist!

  "Fetch an artist by name."
  artistFromName(name: String!): Artist!

  "Search collections."
  collections(
    """
    A search string. We split this up into individual punctuation-less
    token and return collections whose name contain each token.
    """
    search: String
    "If provided, only collections of these type will be returned."
    types: [CollectionType!]
    "If provided, only collections owned by these users will be returned."
    userIds: [Int!]
    "Which page of collections to return."
    page: Int
    """
    The number of collections per-page. Leave null to return all collections
    (and ignore `page`).
    """
    perPage: Int
  ): Collections!

  "Fetch a collection by ID."
  collection(id: Int!): Collection!

  "Fetch a collection by name, type, and user."
  collectionFromNameTypeUser(
    name: String!
    type: CollectionType!
    "The user the collection belongs to."
    user: Int
  ): Collection!

  "Fetch invites."
  invites(
    "Whether to include expired (>24 hours old) invites. False by default"
    includeExpired: Boolean
    "Whether to include used invites. False by default"
    includeUsed: Boolean
    "The user ID of the invite creator."
    createdBy: Int
    "Which page of invites to return."
    page: Int
    """
    The number of invites per-page. Leave null to return all invites.
    """
    perPage: Int
  ): Invites!

  "Fetch invites by ID."
  invite(id: Int!): Invite!

  "Search playlists."
  playlists(
    """
    A search string. We split this up into individual punctuation-less
    token and return playlists whose name contain each token.
    """
    search: String
    "If provided, only playlists of these type will be returned."
    types: [PlaylistType!]
    "If provided, only playlists owned by these users will be returned."
    userIds: [Int!]
    "Which page of playlists to return."
    page: Int
    """
    The number of playlists per-page. Leave null to return all playlists (and
    ignore `page`).
    """
    perPage: Int
  ): Playlists!

  "Fetch a playlist by ID."
  playlist(id: Int!): Playlist!

  "Fetch a playlist by name, type, and user."
  playlistFromNameTypeUser(
    name: String!
    type: PlaylistType!
    "The user the collection belongs to."
    user: Int
  ): Playlist!

  "Search releases."
  releases(
    """
    A search string. We split this up into individual punctuation-less
    token and return releases whose title and artists contain each token.
    """
    search: String
    """
    A list of collection IDs. We match releases by the collections in this
    list. For a release to match, it must be in all collections in this
    list.
    """
    collectionIds: [Int!]
    """
    A list of artist IDs. We match releases by the artists in this list.
    For a release to match, all artists in this list must have participated.
    """
    artistIds: [Int!]
    """
    A list of release types. Filter out releases that do not match one of
    these release types.
    """
    releaseTypes: [ReleaseType!]
    """
    A list of years. Filter out releases that were not released on one of these
    years.
    """
    years: [Int!]
    """
    A list of release types. Filter out releases that do not match one
    of these ratings.
    """
    ratings: [Int!]
    "Which page of releases to return."
    page: Int
    """
    The number of releases per-page. Leave null to return all releases
    (and ignore `page`).
    """
    perPage: Int
    "How to sort the matching releases."
    sort: ReleaseSort
    "If true, sort in ascending order. If false, descending."
    asc: Boolean
  ): Releases!

  "Fetch a release by ID."
  release(id: Int!): Release!

  "Search tracks."
  tracks(
    """
    A search string. We split this up into individual punctuation-less
    token and return tracks whose title and artists contain each token.
    """
    search: String
    """
    A list of playlist IDs. We match tracks by the playlists in this
    list. For a track to match, it must be in all playlists in this
    list.
    """
    playlistIds: [Int!]
    """
    A list of artist IDs. We match track by the artists in this list. For a
    track to match, all artists in this list must have participated.
    """
    artistIds: [Int!]
    """
    A list of years. Filter out tracks that were not released on one of these
    years.
    """
    years: [Int!]
    "Which page of tracks to return."
    page: Int
    """
    The number of tracks per-page. Leave null to return all tracks (and ignore
    `page`).
    """
    perPage: Int
    "How to sort the matching tracks."
    sort: TrackSort
    "If true, sort in ascending order. If false, descending."
    asc: Boolean
  ): Tracks
  "Fetch a track by ID."
  track(id: Int!): Track!

  "Fetch all existing release years sorted in descending order."
  releaseYears: [Int!]!
}

type Mutation {
  "Update the authenticated user."
  updateUser(
    nickname: String
  ): User!

  "Update the application configuration."
  updateConfig(
    "A list of directories to index. Will be validated in the resolver."
    musicDirectories: [String!]
    "A crontab for when to run the indexer. Will be validated in the resolver."
    indexCrontab: String
  ): Config

  """
  Generate a new authentication token for the current user. Invalidate the
  old one.
  """
  newToken: Token!

  createArtist(
    name: String!
  ): Artist!

  updateArtist(
    id: Int!
    name: String
  ): Artist!

  starArtist(
    id: Int!
  ): Artist!

  unstarArtist(
    id: Int!
  ): Artist!

  createCollection(
    name: String!
    type: CollectionType!
  ): Collection!

  updateCollection(
    id: Int!
    name: String
  ): Collection!

  starCollection(
    id: Int!
  ): Collection!

  unstarCollection(
    id: Int!
  ): Collection!

  addReleaseToCollection(
    collectionId: Int!
    releaseId: Int!
  ): CollectionAndRelease!

  delReleaseFromCollection(
    collectionId: Int!
    releaseId: Int!
  ): CollectionAndRelease!

  createInvite: Invite!

  createPlaylist(
    name: String!
    type: PlaylistType!
  ): Playlist!

  updatePlaylist(
    id: Int!
    name: String
  ): Playlist!

  starPlaylist(
    id: Int!
  ): Playlist!

  unstarPlaylist(
    id: Int!
  ): Playlist!

  createPlaylistEntry(
    playlistId: Int!
    trackId: Int!
  ): PlaylistEntry!

  delPlaylistEntry(
    id: Int!
  ): PlaylistAndTrack!

  delPlaylistEntries(
    playlistId: Int!
    trackId: Int!
  ): PlaylistAndTrack!

  updatePlaylistEntry(
    id: Int!
    position: Int!
  ): PlaylistEntry!

  createRelease(
    title: String!
    "A list of artist IDs--the album artists on the release."
    artists: [ArtistWithRoleInput!]!
    releaseType: ReleaseType!
    releaseYear: Int!
    "A date in YYYY-MM-DD format."
    releaseDate: String
    "A rating on the interval [1, 10]."
    rating: Int
  ): Release!

  updateRelease(
    id: Int!
    title: String
    releaseType: ReleaseType,
    releaseYear: Int
    "A date in YYYY-MM-DD format."
    releaseDate: String
    "A rating--pass 0 to delete the existing rating."
    rating: Int
  ): Release!

  addArtistToRelease(
    releaseId: Int!
    artistId: Int!
    role: ArtistRole!
  ): ReleaseAndArtist!

  delArtistFromRelease(
    releaseId: Int!
    artistId: Int!
    role: ArtistRole!
  ): ReleaseAndArtist!

  updateTrack(
    id: Int!
    title: String
    releaseId: Int
    trackNumber: String
    discNumber: String
  ): Track!

  addArtistToTrack(
    trackId: Int!
    artistId: Int!
    role: ArtistRole!
  ): TrackAndArtist!

  delArtistFromTrack(
    trackId: Int!
    artistId: Int!
    role: ArtistRole!
  ): TrackAndArtist!
}

type MusicDirectory {
  directory: String!
  existsOnDisk: Boolean!
}

type Config {
  "A list of directories to index."
  musicDirectories: [MusicDirectory!]!
  "A crontab value for when to run the indexer."
  indexCrontab: String!
}

type Artist {
  id: Int!
  name: String!
  starred: Boolean!
  numReleases: Int!
  "The image ID of one of the artist's releases."
  imageId: Int

  releases: [Release!]!
  "The top genres of the artist, compiled from their releases."
  topGenres: [TopGenre!]!
}

type Artists {
  "The total number of artists matching the query across all pages."
  total: Int!
  "The artists on the current page."
  results: [Artist!]!
}

type ArtistWithRole {
  artist: Artist!
  "The role that the artist has on the track."
  role: ArtistRole!
}

input ArtistWithRoleInput {
  artist_id: Int!
  "The role that the artist has on the track."
  role: ArtistRole!
}

type Collection {
  id: Int!
  name: String!
  starred: Boolean!
  type: CollectionType!
  numReleases: Int!
  "The last datetime a release was added to the collection."
  lastUpdatedOn: PosixTime!
  "The image ID of a release in the collection."
  imageId: Int

  releases: [Release!]!
  "The top genres of the collection, compiled from its releases."
  topGenres: [TopGenre!]!

  "The user the collection belongs to."
  user: User
}

type Collections {
  "The total number of collections matching the query across all pages."
  total: Int!
  "The collections on the current page."
  results: [Collection!]!
}

type Invite {
  id: Int!
  "Hex encoded invite code."
  code: String!
  createdBy: User!
  createdAt: PosixTime!
  usedBy: User
}

type Invites {
  "The total number of invites matching the query across all pages."
  total: Int!
  "The invites on the current page."
  results: [Invite!]!
}

type Playlist {
  id: Int!
  name: String!
  starred: Boolean!
  type: PlaylistType!
  numTracks: Int!
  "The last datetime a release was added to the playlist."
  lastUpdatedOn: PosixTime!
  "The image ID of a track in the playlst. Potentially null."
  imageId: Int

  entries: [PlaylistEntry!]!
  "The top genres of the playlist, compiled from its tracks."
  topGenres: [TopGenre!]!

  "The user the playlist belongs to."
  user: User
}

type Playlists {
  "The total number of playlists matching the query across all pages."
  total: Int!
  "The playlists on the current page."
  results: [Playlist!]!
}

type PlaylistEntry {
  id: Int!
  playlistId: Int!
  trackId: Int!
  position: Int!
  addedOn: PosixTime!

  playlist: Playlist!
  track: Track!
}

type Release {
  id: Int!
  title: String!
  releaseType: ReleaseType!
  addedOn: PosixTime!
  inInbox: Boolean!
  inFavorites: Boolean!
  releaseYear: Int
  "The date that the release was released in YYYY-MM-DD format."
  releaseDate: String
  "The release rating, either null or an int on the interval [1, 10]."
  rating: Int
  numTracks: Int!
  "The total runtime (sum of track durations)."
  runtime: Int!
  "The image ID of the release's cover image."
  imageId: Int

  artists: [ArtistWithRole!]!
  tracks: [Track!]!
  genres: [Collection!]!
  labels: [Collection!]!
  collages: [Collection!]!
}

type Releases {
  "The total number of releases matching the query across all pages."
  total: Int!
  "The releases on the current page."
  results: [Release!]!
}

type Track {
  id: Int!
  title: String!
  duration: Int!
  trackNumber: String!
  discNumber: String!
  "Whether the track is in the user's favorites playlist."
  inFavorites: Boolean!

  release: Release!
  artists: [ArtistWithRole!]!
}

type Tracks {
  "The total number of tracks matching the query across all pages."
  total: Int!
  "The tracks on the current page."
  results: [Track!]!
}

"A type that represents the top genres of an artist/collection."
type TopGenre {
  genre: Collection!
  "The number of releases in the artist/collection that match this genre."
  numMatches: Int!
}

type User {
  id: Int!
  nickname: String!
  inboxCollectionId: Int!
  favoritesCollectionId: Int!
  favoritesPlaylistId: Int!
}

type Token {
  hex: String!
}

type CollectionAndRelease {
  collection: Collection!
  release: Release!
}

type PlaylistAndTrack {
  playlist: Playlist!
  track: Track!
}

type ReleaseAndArtist {
  release: Release!
  artist: Artist!
}

type TrackAndArtist {
  track: Track!
  trackArtist: ArtistWithRole!
}

enum ArtistRole {
  MAIN
  FEATURE
  REMIXER
  PRODUCER
  COMPOSER
  CONDUCTOR
  DJMIXER
}

enum ReleaseType {
  ALBUM
  SINGLE
  EP
  COMPILATION
  SOUNDTRACK
  SPOKENWORD
  LIVE
  REMIX
  DJMIX
  MIXTAPE
  OTHER
  UNKNOWN
}

enum CollectionType {
  SYSTEM
  PERSONAL
  COLLAGE
  LABEL
  GENRE
}

enum ReleaseSort {
  RECENTLY_ADDED
  TITLE
  YEAR
  RATING
  RANDOM
  SEARCH_RANK
}

enum TrackSort {
  RECENTLY_ADDED
  TITLE
  YEAR
  RANDOM
  SEARCH_RANK
}

enum PlaylistType {
  SYSTEM
  PERSONAL
  PLAYLIST
}

Utility Functions

src.graphql.util.commit(func)

A decorator that adds a post-commit on a GraphQL mutation. After a mutation finishes, this decorator will make sure that changes are committed to the database.

Parameters

func (typing.Callable) – The mutation resolver to wrap.

Return type

typing.Callable